+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
- <title>LLVM Assembly Language Reference Manual</title>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="author" content="Chris Lattner">
- <meta name="description"
- content="LLVM Assembly Language Reference Manual.">
- <link rel="stylesheet" href="_static/llvm.css" type="text/css">
-</head>
-
-<body>
-
-<h1>LLVM Language Reference Manual</h1>
-<ol>
- <li><a href="#abstract">Abstract</a></li>
- <li><a href="#introduction">Introduction</a></li>
- <li><a href="#identifiers">Identifiers</a></li>
- <li><a href="#highlevel">High Level Structure</a>
- <ol>
- <li><a href="#modulestructure">Module Structure</a></li>
- <li><a href="#linkage">Linkage Types</a>
- <ol>
- <li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li>
- <li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li>
- <li><a href="#linkage_linker_private_weak">'<tt>linker_private_weak</tt>' Linkage</a></li>
- <li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li>
- <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li>
- <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li>
- <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li>
- <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li>
- <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li>
- <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li>
- <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li>
- <li><a href="#linkage_linkonce_odr_auto_hide">'<tt>linkonce_odr_auto_hide</tt>' Linkage</a></li>
- <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li>
- <li><a href="#linkage_external">'<tt>external</tt>' Linkage</a></li>
- <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li>
- <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li>
- </ol>
- </li>
- <li><a href="#callingconv">Calling Conventions</a></li>
- <li><a href="#namedtypes">Named Types</a></li>
- <li><a href="#globalvars">Global Variables</a></li>
- <li><a href="#functionstructure">Functions</a></li>
- <li><a href="#aliasstructure">Aliases</a></li>
- <li><a href="#namedmetadatastructure">Named Metadata</a></li>
- <li><a href="#paramattrs">Parameter Attributes</a></li>
- <li><a href="#fnattrs">Function Attributes</a></li>
- <li><a href="#gc">Garbage Collector Names</a></li>
- <li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
- <li><a href="#datalayout">Data Layout</a></li>
- <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
- <li><a href="#volatile">Volatile Memory Accesses</a></li>
- <li><a href="#memmodel">Memory Model for Concurrent Operations</a></li>
- <li><a href="#ordering">Atomic Memory Ordering Constraints</a></li>
- <li><a href="#fastmath">Fast-Math Flags</a></li>
- </ol>
- </li>
- <li><a href="#typesystem">Type System</a>
- <ol>
- <li><a href="#t_classifications">Type Classifications</a></li>
- <li><a href="#t_primitive">Primitive Types</a>
- <ol>
- <li><a href="#t_integer">Integer Type</a></li>
- <li><a href="#t_floating">Floating Point Types</a></li>
- <li><a href="#t_x86mmx">X86mmx Type</a></li>
- <li><a href="#t_void">Void Type</a></li>
- <li><a href="#t_label">Label Type</a></li>
- <li><a href="#t_metadata">Metadata Type</a></li>
- </ol>
- </li>
- <li><a href="#t_derived">Derived Types</a>
- <ol>
- <li><a href="#t_aggregate">Aggregate Types</a>
- <ol>
- <li><a href="#t_array">Array Type</a></li>
- <li><a href="#t_struct">Structure Type</a></li>
- <li><a href="#t_opaque">Opaque Structure Types</a></li>
- <li><a href="#t_vector">Vector Type</a></li>
- </ol>
- </li>
- <li><a href="#t_function">Function Type</a></li>
- <li><a href="#t_pointer">Pointer Type</a></li>
- </ol>
- </li>
- </ol>
- </li>
- <li><a href="#constants">Constants</a>
- <ol>
- <li><a href="#simpleconstants">Simple Constants</a></li>
- <li><a href="#complexconstants">Complex Constants</a></li>
- <li><a href="#globalconstants">Global Variable and Function Addresses</a></li>
- <li><a href="#undefvalues">Undefined Values</a></li>
- <li><a href="#poisonvalues">Poison Values</a></li>
- <li><a href="#blockaddress">Addresses of Basic Blocks</a></li>
- <li><a href="#constantexprs">Constant Expressions</a></li>
- </ol>
- </li>
- <li><a href="#othervalues">Other Values</a>
- <ol>
- <li><a href="#inlineasm">Inline Assembler Expressions</a></li>
- <li><a href="#metadata">Metadata Nodes and Metadata Strings</a>
- <ol>
- <li><a href="#tbaa">'<tt>tbaa</tt>' Metadata</a></li>
- <li><a href="#tbaa.struct">'<tt>tbaa.struct</tt>' Metadata</a></li>
- <li><a href="#fpmath">'<tt>fpmath</tt>' Metadata</a></li>
- <li><a href="#range">'<tt>range</tt>' Metadata</a></li>
- </ol>
- </li>
- </ol>
- </li>
- <li><a href="#module_flags">Module Flags Metadata</a>
- <ol>
- <li><a href="#objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a></li>
- </ol>
- </li>
- <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
- <ol>
- <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li>
- <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>'
- Global Variable</a></li>
- <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>'
- Global Variable</a></li>
- <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>'
- Global Variable</a></li>
- </ol>
- </li>
- <li><a href="#instref">Instruction Reference</a>
- <ol>
- <li><a href="#terminators">Terminator Instructions</a>
- <ol>
- <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
- <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
- <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
- <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li>
- <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
- <li><a href="#i_resume">'<tt>resume</tt>' Instruction</a></li>
- <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
- </ol>
- </li>
- <li><a href="#binaryops">Binary Operations</a>
- <ol>
- <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
- <li><a href="#i_fadd">'<tt>fadd</tt>' Instruction</a></li>
- <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
- <li><a href="#i_fsub">'<tt>fsub</tt>' Instruction</a></li>
- <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
- <li><a href="#i_fmul">'<tt>fmul</tt>' Instruction</a></li>
- <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
- <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
- <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
- <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
- <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
- <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
- </ol>
- </li>
- <li><a href="#bitwiseops">Bitwise Binary Operations</a>
- <ol>
- <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
- <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
- <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
- <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
- <li><a href="#i_or">'<tt>or</tt>' Instruction</a></li>
- <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
- </ol>
- </li>
- <li><a href="#vectorops">Vector Operations</a>
- <ol>
- <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
- <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
- <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
- </ol>
- </li>
- <li><a href="#aggregateops">Aggregate Operations</a>
- <ol>
- <li><a href="#i_extractvalue">'<tt>extractvalue</tt>' Instruction</a></li>
- <li><a href="#i_insertvalue">'<tt>insertvalue</tt>' Instruction</a></li>
- </ol>
- </li>
- <li><a href="#memoryops">Memory Access and Addressing Operations</a>
- <ol>
- <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li>
- <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li>
- <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li>
- <li><a href="#i_fence">'<tt>fence</tt>' Instruction</a></li>
- <li><a href="#i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a></li>
- <li><a href="#i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a></li>
- <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
- </ol>
- </li>
- <li><a href="#convertops">Conversion Operations</a>
- <ol>
- <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
- <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
- <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
- <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
- <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
- <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
- <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
- <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
- <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
- <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
- <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
- <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
- </ol>
- </li>
- <li><a href="#otherops">Other Operations</a>
- <ol>
- <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
- <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
- <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li>
- <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
- <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li>
- <li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a></li>
- <li><a href="#i_landingpad">'<tt>landingpad</tt>' Instruction</a></li>
- </ol>
- </li>
- </ol>
- </li>
- <li><a href="#intrinsics">Intrinsic Functions</a>
- <ol>
- <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
- <ol>
- <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
- <li><a href="#int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li>
- <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
- <ol>
- <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
- <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
- <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_codegen">Code Generator Intrinsics</a>
- <ol>
- <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
- <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li>
- <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
- <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
- <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
- <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
- <li><a href="#int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_libc">Standard C Library Intrinsics</a>
- <ol>
- <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
- <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
- <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
- <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
- <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
- <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li>
- <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li>
- <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li>
- <li><a href="#int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a></li>
- <li><a href="#int_exp2">'<tt>llvm.exp2.*</tt>' Intrinsic</a></li>
- <li><a href="#int_log">'<tt>llvm.log.*</tt>' Intrinsic</a></li>
- <li><a href="#int_log10">'<tt>llvm.log10.*</tt>' Intrinsic</a></li>
- <li><a href="#int_log2">'<tt>llvm.log2.*</tt>' Intrinsic</a></li>
- <li><a href="#int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a></li>
- <li><a href="#int_fabs">'<tt>llvm.fabs.*</tt>' Intrinsic</a></li>
- <li><a href="#int_floor">'<tt>llvm.floor.*</tt>' Intrinsic</a></li>
- <li><a href="#int_ceil">'<tt>llvm.ceil.*</tt>' Intrinsic</a></li>
- <li><a href="#int_trunc">'<tt>llvm.trunc.*</tt>' Intrinsic</a></li>
- <li><a href="#int_rint">'<tt>llvm.rint.*</tt>' Intrinsic</a></li>
- <li><a href="#int_nearbyint">'<tt>llvm.nearbyint.*</tt>' Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_manip">Bit Manipulation Intrinsics</a>
- <ol>
- <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
- <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
- <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
- <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
- </ol>
- </li>
- <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a>
- <ol>
- <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li>
- <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li>
- <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li>
- <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li>
- <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li>
- <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
- </ol>
- </li>
- <li><a href="#spec_arithmetic">Specialised Arithmetic Intrinsics</a>
- <ol>
- <li><a href="#fmuladd">'<tt>llvm.fmuladd</tt> Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a>
- <ol>
- <li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li>
- <li><a href="#int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_debugger">Debugger intrinsics</a></li>
- <li><a href="#int_eh">Exception Handling intrinsics</a></li>
- <li><a href="#int_trampoline">Trampoline Intrinsics</a>
- <ol>
- <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
- <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_memorymarkers">Memory Use Markers</a>
- <ol>
- <li><a href="#int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a></li>
- <li><a href="#int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a></li>
- <li><a href="#int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a></li>
- <li><a href="#int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a></li>
- </ol>
- </li>
- <li><a href="#int_general">General intrinsics</a>
- <ol>
- <li><a href="#int_var_annotation">
- '<tt>llvm.var.annotation</tt>' Intrinsic</a></li>
- <li><a href="#int_annotation">
- '<tt>llvm.annotation.*</tt>' Intrinsic</a></li>
- <li><a href="#int_trap">
- '<tt>llvm.trap</tt>' Intrinsic</a></li>
- <li><a href="#int_debugtrap">
- '<tt>llvm.debugtrap</tt>' Intrinsic</a></li>
- <li><a href="#int_stackprotector">
- '<tt>llvm.stackprotector</tt>' Intrinsic</a></li>
- <li><a href="#int_objectsize">
- '<tt>llvm.objectsize</tt>' Intrinsic</a></li>
- <li><a href="#int_expect">
- '<tt>llvm.expect</tt>' Intrinsic</a></li>
- <li><a href="#int_donothing">
- '<tt>llvm.donothing</tt>' Intrinsic</a></li>
- </ol>
- </li>
- </ol>
- </li>
-</ol>
-
-<div class="doc_author">
- <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
- and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="abstract">Abstract</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>This document is a reference manual for the LLVM assembly language. LLVM is
- a Static Single Assignment (SSA) based representation that provides type
- safety, low-level operations, flexibility, and the capability of representing
- 'all' high-level languages cleanly. It is the common code representation
- used throughout all phases of the LLVM compilation strategy.</p>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="introduction">Introduction</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>The LLVM code representation is designed to be used in three different forms:
- as an in-memory compiler IR, as an on-disk bitcode representation (suitable
- for fast loading by a Just-In-Time compiler), and as a human readable
- assembly language representation. This allows LLVM to provide a powerful
- intermediate representation for efficient compiler transformations and
- analysis, while providing a natural means to debug and visualize the
- transformations. The three different forms of LLVM are all equivalent. This
- document describes the human readable representation and notation.</p>
-
-<p>The LLVM representation aims to be light-weight and low-level while being
- expressive, typed, and extensible at the same time. It aims to be a
- "universal IR" of sorts, by being at a low enough level that high-level ideas
- may be cleanly mapped to it (similar to how microprocessors are "universal
- IR's", allowing many source languages to be mapped to them). By providing
- type information, LLVM can be used as the target of optimizations: for
- example, through pointer analysis, it can be proven that a C automatic
- variable is never accessed outside of the current function, allowing it to
- be promoted to a simple SSA value instead of a memory location.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="wellformed">Well-Formedness</a>
-</h4>
-
-<div>
-
-<p>It is important to note that this document describes 'well formed' LLVM
- assembly language. There is a difference between what the parser accepts and
- what is considered 'well formed'. For example, the following instruction is
- syntactically okay, but not well formed:</p>
-
-<pre class="doc_code">
-%x = <a href="#i_add">add</a> i32 1, %x
-</pre>
-
-<p>because the definition of <tt>%x</tt> does not dominate all of its uses. The
- LLVM infrastructure provides a verification pass that may be used to verify
- that an LLVM module is well formed. This pass is automatically run by the
- parser after parsing input assembly and by the optimizer before it outputs
- bitcode. The violations pointed out by the verifier pass indicate bugs in
- transformation passes or input to the parser.</p>
-
-</div>
-
-</div>
-
-<!-- Describe the typesetting conventions here. -->
-
-<!-- *********************************************************************** -->
-<h2><a name="identifiers">Identifiers</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>LLVM identifiers come in two basic types: global and local. Global
- identifiers (functions, global variables) begin with the <tt>'@'</tt>
- character. Local identifiers (register names, types) begin with
- the <tt>'%'</tt> character. Additionally, there are three different formats
- for identifiers, for different purposes:</p>
-
-<ol>
- <li>Named values are represented as a string of characters with their prefix.
- For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>,
- <tt>%a.really.long.identifier</tt>. The actual regular expression used is
- '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. Identifiers which require
- other characters in their names can be surrounded with quotes. Special
- characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the
- ASCII code for the character in hexadecimal. In this way, any character
- can be used in a name value, even quotes themselves.</li>
-
- <li>Unnamed values are represented as an unsigned numeric value with their
- prefix. For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li>
-
- <li>Constants, which are described in a <a href="#constants">section about
- constants</a>, below.</li>
-</ol>
-
-<p>LLVM requires that values start with a prefix for two reasons: Compilers
- don't need to worry about name clashes with reserved words, and the set of
- reserved words may be expanded in the future without penalty. Additionally,
- unnamed identifiers allow a compiler to quickly come up with a temporary
- variable without having to avoid symbol table conflicts.</p>
-
-<p>Reserved words in LLVM are very similar to reserved words in other
- languages. There are keywords for different opcodes
- ('<tt><a href="#i_add">add</a></tt>',
- '<tt><a href="#i_bitcast">bitcast</a></tt>',
- '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names
- ('<tt><a href="#t_void">void</a></tt>',
- '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others. These
- reserved words cannot conflict with variable names, because none of them
- start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p>
-
-<p>Here is an example of LLVM code to multiply the integer variable
- '<tt>%X</tt>' by 8:</p>
-
-<p>The easy way:</p>
-
-<pre class="doc_code">
-%result = <a href="#i_mul">mul</a> i32 %X, 8
-</pre>
-
-<p>After strength reduction:</p>
-
-<pre class="doc_code">
-%result = <a href="#i_shl">shl</a> i32 %X, i8 3
-</pre>
-
-<p>And the hard way:</p>
-
-<pre class="doc_code">
-%0 = <a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i>
-%1 = <a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i>
-%result = <a href="#i_add">add</a> i32 %1, %1
-</pre>
-
-<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
- lexical features of LLVM:</p>
-
-<ol>
- <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
- line.</li>
-
- <li>Unnamed temporaries are created when the result of a computation is not
- assigned to a named value.</li>
-
- <li>Unnamed temporaries are numbered sequentially</li>
-</ol>
-
-<p>It also shows a convention that we follow in this document. When
- demonstrating instructions, we will follow an instruction with a comment that
- defines the type and name of value produced. Comments are shown in italic
- text.</p>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="highlevel">High Level Structure</a></h2>
-<!-- *********************************************************************** -->
-<div>
-<!-- ======================================================================= -->
-<h3>
- <a name="modulestructure">Module Structure</a>
-</h3>
-
-<div>
-
-<p>LLVM programs are composed of <tt>Module</tt>s, each of which is a
- translation unit of the input programs. Each module consists of functions,
- global variables, and symbol table entries. Modules may be combined together
- with the LLVM linker, which merges function (and global variable)
- definitions, resolves forward declarations, and merges symbol table
- entries. Here is an example of the "hello world" module:</p>
-
-<pre class="doc_code">
-<i>; Declare the string constant as a global constant.</i>
-<a href="#identifiers">@.str</a> = <a href="#linkage_private">private</a> <a href="#globalvars">unnamed_addr</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00"
-
-<i>; External declaration of the puts function</i>
-<a href="#functionstructure">declare</a> i32 @puts(i8* <a href="#nocapture">nocapture</a>) <a href="#fnattrs">nounwind</a>
-
-<i>; Definition of main function</i>
-define i32 @main() { <i>; i32()* </i>
- <i>; Convert [13 x i8]* to i8 *...</i>
- %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.str, i64 0, i64 0
-
- <i>; Call puts function to write out the string to stdout.</i>
- <a href="#i_call">call</a> i32 @puts(i8* %cast210)
- <a href="#i_ret">ret</a> i32 0
-}
-
-<i>; Named metadata</i>
-!1 = metadata !{i32 42}
-!foo = !{!1, null}
-</pre>
-
-<p>This example is made up of a <a href="#globalvars">global variable</a> named
- "<tt>.str</tt>", an external declaration of the "<tt>puts</tt>" function,
- a <a href="#functionstructure">function definition</a> for
- "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a>
- "<tt>foo</tt>".</p>
-
-<p>In general, a module is made up of a list of global values (where both
- functions and global variables are global values). Global values are
- represented by a pointer to a memory location (in this case, a pointer to an
- array of char, and a pointer to a function), and have one of the
- following <a href="#linkage">linkage types</a>.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="linkage">Linkage Types</a>
-</h3>
-
-<div>
-
-<p>All Global Variables and Functions have one of the following types of
- linkage:</p>
-
-<dl>
- <dt><tt><b><a name="linkage_private">private</a></b></tt></dt>
- <dd>Global values with "<tt>private</tt>" linkage are only directly accessible
- by objects in the current module. In particular, linking code into a
- module with an private global value may cause the private to be renamed as
- necessary to avoid collisions. Because the symbol is private to the
- module, all references can be updated. This doesn't show up in any symbol
- table in the object file.</dd>
-
- <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt></dt>
- <dd>Similar to <tt>private</tt>, but the symbol is passed through the
- assembler and evaluated by the linker. Unlike normal strong symbols, they
- are removed by the linker from the final linked image (executable or
- dynamic library).</dd>
-
- <dt><tt><b><a name="linkage_linker_private_weak">linker_private_weak</a></b></tt></dt>
- <dd>Similar to "<tt>linker_private</tt>", but the symbol is weak. Note that
- <tt>linker_private_weak</tt> symbols are subject to coalescing by the
- linker. The symbols are removed by the linker from the final linked image
- (executable or dynamic library).</dd>
-
- <dt><tt><b><a name="linkage_internal">internal</a></b></tt></dt>
- <dd>Similar to private, but the value shows as a local symbol
- (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This
- corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd>
-
- <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt></dt>
- <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted
- into the object file corresponding to the LLVM module. They exist to
- allow inlining and other optimizations to take place given knowledge of
- the definition of the global, which is known to be somewhere outside the
- module. Globals with <tt>available_externally</tt> linkage are allowed to
- be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>.
- This linkage type is only allowed on definitions, not declarations.</dd>
-
- <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt></dt>
- <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
- the same name when linkage occurs. This can be used to implement
- some forms of inline functions, templates, or other code which must be
- generated in each translation unit that uses it, but where the body may
- be overridden with a more definitive definition later. Unreferenced
- <tt>linkonce</tt> globals are allowed to be discarded. Note that
- <tt>linkonce</tt> linkage does not actually allow the optimizer to
- inline the body of this function into callers because it doesn't know if
- this definition of the function is the definitive definition within the
- program or whether it will be overridden by a stronger definition.
- To enable inlining and other optimizations, use "<tt>linkonce_odr</tt>"
- linkage.</dd>
-
- <dt><tt><b><a name="linkage_weak">weak</a></b></tt></dt>
- <dd>"<tt>weak</tt>" linkage has the same merging semantics as
- <tt>linkonce</tt> linkage, except that unreferenced globals with
- <tt>weak</tt> linkage may not be discarded. This is used for globals that
- are declared "weak" in C source code.</dd>
-
- <dt><tt><b><a name="linkage_common">common</a></b></tt></dt>
- <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
- they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
- global scope.
- Symbols with "<tt>common</tt>" linkage are merged in the same way as
- <tt>weak symbols</tt>, and they may not be deleted if unreferenced.
- <tt>common</tt> symbols may not have an explicit section,
- must have a zero initializer, and may not be marked '<a
- href="#globalvars"><tt>constant</tt></a>'. Functions and aliases may not
- have common linkage.</dd>
-
-
- <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt>
- <dd>"<tt>appending</tt>" linkage may only be applied to global variables of
- pointer to array type. When two global variables with appending linkage
- are linked together, the two global arrays are appended together. This is
- the LLVM, typesafe, equivalent of having the system linker append together
- "sections" with identical names when .o files are linked.</dd>
-
- <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt></dt>
- <dd>The semantics of this linkage follow the ELF object file model: the symbol
- is weak until linked, if not linked, the symbol becomes null instead of
- being an undefined reference.</dd>
-
- <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt></dt>
- <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt></dt>
- <dd>Some languages allow differing globals to be merged, such as two functions
- with different semantics. Other languages, such as <tt>C++</tt>, ensure
- that only equivalent globals are ever merged (the "one definition rule"
- — "ODR"). Such languages can use the <tt>linkonce_odr</tt>
- and <tt>weak_odr</tt> linkage types to indicate that the global will only
- be merged with equivalent globals. These linkage types are otherwise the
- same as their non-<tt>odr</tt> versions.</dd>
-
- <dt><tt><b><a name="linkage_linkonce_odr_auto_hide">linkonce_odr_auto_hide</a></b></tt></dt>
- <dd>Similar to "<tt>linkonce_odr</tt>", but nothing in the translation unit
- takes the address of this definition. For instance, functions that had an
- inline definition, but the compiler decided not to inline it.
- <tt>linkonce_odr_auto_hide</tt> may have only <tt>default</tt> visibility.
- The symbols are removed by the linker from the final linked image
- (executable or dynamic library).</dd>
-
- <dt><tt><b><a name="linkage_external">external</a></b></tt></dt>
- <dd>If none of the above identifiers are used, the global is externally
- visible, meaning that it participates in linkage and can be used to
- resolve external symbol references.</dd>
-</dl>
-
-<p>The next two types of linkage are targeted for Microsoft Windows platform
- only. They are designed to support importing (exporting) symbols from (to)
- DLLs (Dynamic Link Libraries).</p>
-
-<dl>
- <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt>
- <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
- or variable via a global pointer to a pointer that is set up by the DLL
- exporting the symbol. On Microsoft Windows targets, the pointer name is
- formed by combining <code>__imp_</code> and the function or variable
- name.</dd>
-
- <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt></dt>
- <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
- pointer to a pointer in a DLL, so that it can be referenced with the
- <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
- name is formed by combining <code>__imp_</code> and the function or
- variable name.</dd>
-</dl>
-
-<p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
- another module defined a "<tt>.LC0</tt>" variable and was linked with this
- one, one of the two would be renamed, preventing a collision. Since
- "<tt>main</tt>" and "<tt>puts</tt>" are external (i.e., lacking any linkage
- declarations), they are accessible outside of the current module.</p>
-
-<p>It is illegal for a function <i>declaration</i> to have any linkage type
- other than <tt>external</tt>, <tt>dllimport</tt>
- or <tt>extern_weak</tt>.</p>
-
-<p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt>
- or <tt>weak_odr</tt> linkages.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="callingconv">Calling Conventions</a>
-</h3>
-
-<div>
-
-<p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
- and <a href="#i_invoke">invokes</a> can all have an optional calling
- convention specified for the call. The calling convention of any pair of
- dynamic caller/callee must match, or the behavior of the program is
- undefined. The following calling conventions are supported by LLVM, and more
- may be added in the future:</p>
-
-<dl>
- <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
- <dd>This calling convention (the default if no other calling convention is
- specified) matches the target C calling conventions. This calling
- convention supports varargs function calls and tolerates some mismatch in
- the declared prototype and implemented declaration of the function (as
- does normal C).</dd>
-
- <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
- <dd>This calling convention attempts to make calls as fast as possible
- (e.g. by passing things in registers). This calling convention allows the
- target to use whatever tricks it wants to produce fast code for the
- target, without having to conform to an externally specified ABI
- (Application Binary Interface).
- <a href="CodeGenerator.html#id80">Tail calls can only be optimized
- when this, the GHC or the HiPE convention is used.</a> This calling
- convention does not support varargs and requires the prototype of all
- callees to exactly match the prototype of the function definition.</dd>
-
- <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
- <dd>This calling convention attempts to make code in the caller as efficient
- as possible under the assumption that the call is not commonly executed.
- As such, these calls often preserve all registers so that the call does
- not break any live ranges in the caller side. This calling convention
- does not support varargs and requires the prototype of all callees to
- exactly match the prototype of the function definition.</dd>
-
- <dt><b>"<tt>cc <em>10</em></tt>" - GHC convention</b>:</dt>
- <dd>This calling convention has been implemented specifically for use by the
- <a href="http://www.haskell.org/ghc">Glasgow Haskell Compiler (GHC)</a>.
- It passes everything in registers, going to extremes to achieve this by
- disabling callee save registers. This calling convention should not be
- used lightly but only for specific situations such as an alternative to
- the <em>register pinning</em> performance technique often used when
- implementing functional programming languages. At the moment only X86
- supports this convention and it has the following limitations:
- <ul>
- <li>On <em>X86-32</em> only supports up to 4 bit type parameters. No
- floating point types are supported.</li>
- <li>On <em>X86-64</em> only supports up to 10 bit type parameters and
- 6 floating point parameters.</li>
- </ul>
- This calling convention supports
- <a href="CodeGenerator.html#id80">tail call optimization</a> but
- requires both the caller and callee are using it.
- </dd>
-
- <dt><b>"<tt>cc <em>11</em></tt>" - The HiPE calling convention</b>:</dt>
- <dd>This calling convention has been implemented specifically for use by the
- <a href="http://www.it.uu.se/research/group/hipe/">High-Performance Erlang
- (HiPE)</a> compiler, <em>the</em> native code compiler of the
- <a href="http://www.erlang.org/download.shtml">Ericsson's Open Source
- Erlang/OTP system</a>. It uses more registers for argument passing than
- the ordinary C calling convention and defines no callee-saved registers.
- The calling convention properly supports
- <a href="CodeGenerator.html#id80">tail call optimization</a> but requires
- that both the caller and the callee use it. It uses a <em>register
- pinning</em> mechanism, similar to GHC's convention, for keeping
- frequently accessed runtime components pinned to specific hardware
- registers. At the moment only X86 supports this convention (both 32 and 64
- bit).</dd>
-
- <dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt>
- <dd>Any calling convention may be specified by number, allowing
- target-specific calling conventions to be used. Target specific calling
- conventions start at 64.</dd>
-</dl>
-
-<p>More calling conventions can be added/defined on an as-needed basis, to
- support Pascal conventions or any other well-known target-independent
- convention.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="visibility">Visibility Styles</a>
-</h3>
-
-<div>
-
-<p>All Global Variables and Functions have one of the following visibility
- styles:</p>
-
-<dl>
- <dt><b>"<tt>default</tt>" - Default style</b>:</dt>
- <dd>On targets that use the ELF object file format, default visibility means
- that the declaration is visible to other modules and, in shared libraries,
- means that the declared entity may be overridden. On Darwin, default
- visibility means that the declaration is visible to other modules. Default
- visibility corresponds to "external linkage" in the language.</dd>
-
- <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt>
- <dd>Two declarations of an object with hidden visibility refer to the same
- object if they are in the same shared object. Usually, hidden visibility
- indicates that the symbol will not be placed into the dynamic symbol
- table, so no other module (executable or shared library) can reference it
- directly.</dd>
-
- <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt>
- <dd>On ELF, protected visibility indicates that the symbol will be placed in
- the dynamic symbol table, but that references within the defining module
- will bind to the local symbol. That is, the symbol cannot be overridden by
- another module.</dd>
-</dl>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="namedtypes">Named Types</a>
-</h3>
-
-<div>
-
-<p>LLVM IR allows you to specify name aliases for certain types. This can make
- it easier to read the IR and make the IR more condensed (particularly when
- recursive types are involved). An example of a name specification is:</p>
-
-<pre class="doc_code">
-%mytype = type { %mytype*, i32 }
-</pre>
-
-<p>You may give a name to any <a href="#typesystem">type</a> except
- "<a href="#t_void">void</a>". Type name aliases may be used anywhere a type
- is expected with the syntax "%mytype".</p>
-
-<p>Note that type names are aliases for the structural type that they indicate,
- and that you can therefore specify multiple names for the same type. This
- often leads to confusing behavior when dumping out a .ll file. Since LLVM IR
- uses structural typing, the name is not part of the type. When printing out
- LLVM IR, the printer will pick <em>one name</em> to render all types of a
- particular shape. This means that if you have code where two different
- source types end up having the same LLVM type, that the dumper will sometimes
- print the "wrong" or unexpected type. This is an important design point and
- isn't going to change.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="globalvars">Global Variables</a>
-</h3>
-
-<div>
-
-<p>Global variables define regions of memory allocated at compilation time
- instead of run-time. Global variables may optionally be initialized, may
- have an explicit section to be placed in, and may have an optional explicit
- alignment specified.</p>
-
-<p>A variable may be defined as <tt>thread_local</tt>, which
- means that it will not be shared by threads (each thread will have a
- separated copy of the variable). Not all targets support thread-local
- variables. Optionally, a TLS model may be specified:</p>
-
-<dl>
- <dt><b><tt>localdynamic</tt></b>:</dt>
- <dd>For variables that are only used within the current shared library.</dd>
-
- <dt><b><tt>initialexec</tt></b>:</dt>
- <dd>For variables in modules that will not be loaded dynamically.</dd>
-
- <dt><b><tt>localexec</tt></b>:</dt>
- <dd>For variables defined in the executable and only used within it.</dd>
-</dl>
-
-<p>The models correspond to the ELF TLS models; see
- <a href="http://people.redhat.com/drepper/tls.pdf">ELF
- Handling For Thread-Local Storage</a> for more information on under which
- circumstances the different models may be used. The target may choose a
- different TLS model if the specified model is not supported, or if a better
- choice of model can be made.</p>
-
-<p>A variable may be defined as a global
- "constant," which indicates that the contents of the variable
- will <b>never</b> be modified (enabling better optimization, allowing the
- global data to be placed in the read-only section of an executable, etc).
- Note that variables that need runtime initialization cannot be marked
- "constant" as there is a store to the variable.</p>
-
-<p>LLVM explicitly allows <em>declarations</em> of global variables to be marked
- constant, even if the final definition of the global is not. This capability
- can be used to enable slightly better optimization of the program, but
- requires the language definition to guarantee that optimizations based on the
- 'constantness' are valid for the translation units that do not include the
- definition.</p>
-
-<p>As SSA values, global variables define pointer values that are in scope
- (i.e. they dominate) all basic blocks in the program. Global variables
- always define a pointer to their "content" type because they describe a
- region of memory, and all memory objects in LLVM are accessed through
- pointers.</p>
-
-<p>Global variables can be marked with <tt>unnamed_addr</tt> which indicates
- that the address is not significant, only the content. Constants marked
- like this can be merged with other constants if they have the same
- initializer. Note that a constant with significant address <em>can</em>
- be merged with a <tt>unnamed_addr</tt> constant, the result being a
- constant whose address is significant.</p>
-
-<p>A global variable may be declared to reside in a target-specific numbered
- address space. For targets that support them, address spaces may affect how
- optimizations are performed and/or what target instructions are used to
- access the variable. The default address space is zero. The address space
- qualifier must precede any other attributes.</p>
-
-<p>LLVM allows an explicit section to be specified for globals. If the target
- supports it, it will emit globals to the section specified.</p>
-
-<p>An explicit alignment may be specified for a global, which must be a power
- of 2. If not present, or if the alignment is set to zero, the alignment of
- the global is set by the target to whatever it feels convenient. If an
- explicit alignment is specified, the global is forced to have exactly that
- alignment. Targets and optimizers are not allowed to over-align the global
- if the global has an assigned section. In this case, the extra alignment
- could be observable: for example, code could assume that the globals are
- densely packed in their section and try to iterate over them as an array,
- alignment padding would break this iteration.</p>
-
-<p>For example, the following defines a global in a numbered address space with
- an initializer, section, and alignment:</p>
-
-<pre class="doc_code">
-@G = addrspace(5) constant float 1.0, section "foo", align 4
-</pre>
-
-<p>The following example defines a thread-local global with
- the <tt>initialexec</tt> TLS model:</p>
-
-<pre class="doc_code">
-@G = thread_local(initialexec) global i32 0, align 4
-</pre>
-
-</div>
-
-
-<!-- ======================================================================= -->
-<h3>
- <a name="functionstructure">Functions</a>
-</h3>
-
-<div>
-
-<p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an
- optional <a href="#linkage">linkage type</a>, an optional
- <a href="#visibility">visibility style</a>, an optional
- <a href="#callingconv">calling convention</a>,
- an optional <tt>unnamed_addr</tt> attribute, a return type, an optional
- <a href="#paramattrs">parameter attribute</a> for the return type, a function
- name, a (possibly empty) argument list (each with optional
- <a href="#paramattrs">parameter attributes</a>), optional
- <a href="#fnattrs">function attributes</a>, an optional section, an optional
- alignment, an optional <a href="#gc">garbage collector name</a>, an opening
- curly brace, a list of basic blocks, and a closing curly brace.</p>
-
-<p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
- optional <a href="#linkage">linkage type</a>, an optional
- <a href="#visibility">visibility style</a>, an optional
- <a href="#callingconv">calling convention</a>,
- an optional <tt>unnamed_addr</tt> attribute, a return type, an optional
- <a href="#paramattrs">parameter attribute</a> for the return type, a function
- name, a possibly empty list of arguments, an optional alignment, and an
- optional <a href="#gc">garbage collector name</a>.</p>
-
-<p>A function definition contains a list of basic blocks, forming the CFG
- (Control Flow Graph) for the function. Each basic block may optionally start
- with a label (giving the basic block a symbol table entry), contains a list
- of instructions, and ends with a <a href="#terminators">terminator</a>
- instruction (such as a branch or function return).</p>
-
-<p>The first basic block in a function is special in two ways: it is immediately
- executed on entrance to the function, and it is not allowed to have
- predecessor basic blocks (i.e. there can not be any branches to the entry
- block of a function). Because the block can have no predecessors, it also
- cannot have any <a href="#i_phi">PHI nodes</a>.</p>
-
-<p>LLVM allows an explicit section to be specified for functions. If the target
- supports it, it will emit functions to the section specified.</p>
-
-<p>An explicit alignment may be specified for a function. If not present, or if
- the alignment is set to zero, the alignment of the function is set by the
- target to whatever it feels convenient. If an explicit alignment is
- specified, the function is forced to have at least that much alignment. All
- alignments must be a power of 2.</p>
-
-<p>If the <tt>unnamed_addr</tt> attribute is given, the address is know to not
- be significant and two identical functions can be merged.</p>
-
-<h5>Syntax:</h5>
-<pre class="doc_code">
-define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
- [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>]
- <ResultType> @<FunctionName> ([argument list])
- [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N]
- [<a href="#gc">gc</a>] { ... }
-</pre>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="aliasstructure">Aliases</a>
-</h3>
-
-<div>
-
-<p>Aliases act as "second name" for the aliasee value (which can be either
- function, global variable, another alias or bitcast of global value). Aliases
- may have an optional <a href="#linkage">linkage type</a>, and an
- optional <a href="#visibility">visibility style</a>.</p>
-
-<h5>Syntax:</h5>
-<pre class="doc_code">
-@<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
-</pre>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="namedmetadatastructure">Named Metadata</a>
-</h3>
-
-<div>
-
-<p>Named metadata is a collection of metadata. <a href="#metadata">Metadata
- nodes</a> (but not metadata strings) are the only valid operands for
- a named metadata.</p>
-
-<h5>Syntax:</h5>
-<pre class="doc_code">
-; Some unnamed metadata nodes, which are referenced by the named metadata.
-!0 = metadata !{metadata !"zero"}
-!1 = metadata !{metadata !"one"}
-!2 = metadata !{metadata !"two"}
-; A named metadata.
-!name = !{!0, !1, !2}
-</pre>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="paramattrs">Parameter Attributes</a>
-</h3>
-
-<div>
-
-<p>The return type and each parameter of a function type may have a set of
- <i>parameter attributes</i> associated with them. Parameter attributes are
- used to communicate additional information about the result or parameters of
- a function. Parameter attributes are considered to be part of the function,
- not of the function type, so functions with different parameter attributes
- can have the same function type.</p>
-
-<p>Parameter attributes are simple keywords that follow the type specified. If
- multiple parameter attributes are needed, they are space separated. For
- example:</p>
-
-<pre class="doc_code">
-declare i32 @printf(i8* noalias nocapture, ...)
-declare i32 @atoi(i8 zeroext)
-declare signext i8 @returns_signed_char()
-</pre>
-
-<p>Note that any attributes for the function result (<tt>nounwind</tt>,
- <tt>readonly</tt>) come immediately after the argument list.</p>
-
-<p>Currently, only the following parameter attributes are defined:</p>
-
-<dl>
- <dt><tt><b>zeroext</b></tt></dt>
- <dd>This indicates to the code generator that the parameter or return value
- should be zero-extended to the extent required by the target's ABI (which
- is usually 32-bits, but is 8-bits for a i1 on x86-64) by the caller (for a
- parameter) or the callee (for a return value).</dd>
-
- <dt><tt><b>signext</b></tt></dt>
- <dd>This indicates to the code generator that the parameter or return value
- should be sign-extended to the extent required by the target's ABI (which
- is usually 32-bits) by the caller (for a parameter) or the callee (for a
- return value).</dd>
-
- <dt><tt><b>inreg</b></tt></dt>
- <dd>This indicates that this parameter or return value should be treated in a
- special target-dependent fashion during while emitting code for a function
- call or return (usually, by putting it in a register as opposed to memory,
- though some targets use it to distinguish between two different kinds of
- registers). Use of this attribute is target-specific.</dd>
-
- <dt><tt><b><a name="byval">byval</a></b></tt></dt>
- <dd><p>This indicates that the pointer parameter should really be passed by
- value to the function. The attribute implies that a hidden copy of the
- pointee
- is made between the caller and the callee, so the callee is unable to
- modify the value in the caller. This attribute is only valid on LLVM
- pointer arguments. It is generally used to pass structs and arrays by
- value, but is also valid on pointers to scalars. The copy is considered
- to belong to the caller not the callee (for example,
- <tt><a href="#readonly">readonly</a></tt> functions should not write to
- <tt>byval</tt> parameters). This is not a valid attribute for return
- values.</p>
-
- <p>The byval attribute also supports specifying an alignment with
- the align attribute. It indicates the alignment of the stack slot to
- form and the known alignment of the pointer specified to the call site. If
- the alignment is not specified, then the code generator makes a
- target-specific assumption.</p></dd>
-
- <dt><tt><b><a name="sret">sret</a></b></tt></dt>
- <dd>This indicates that the pointer parameter specifies the address of a
- structure that is the return value of the function in the source program.
- This pointer must be guaranteed by the caller to be valid: loads and
- stores to the structure may be assumed by the callee to not to trap and
- to be properly aligned. This may only be applied to the first parameter.
- This is not a valid attribute for return values. </dd>
-
- <dt><tt><b><a name="noalias">noalias</a></b></tt></dt>
- <dd>This indicates that pointer values
- <a href="#pointeraliasing"><i>based</i></a> on the argument or return
- value do not alias pointer values which are not <i>based</i> on it,
- ignoring certain "irrelevant" dependencies.
- For a call to the parent function, dependencies between memory
- references from before or after the call and from those during the call
- are "irrelevant" to the <tt>noalias</tt> keyword for the arguments and
- return value used in that call.
- The caller shares the responsibility with the callee for ensuring that
- these requirements are met.
- For further details, please see the discussion of the NoAlias response in
- <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.<br>
-<br>
- Note that this definition of <tt>noalias</tt> is intentionally
- similar to the definition of <tt>restrict</tt> in C99 for function
- arguments, though it is slightly weaker.
-<br>
- For function return values, C99's <tt>restrict</tt> is not meaningful,
- while LLVM's <tt>noalias</tt> is.
- </dd>
-
- <dt><tt><b><a name="nocapture">nocapture</a></b></tt></dt>
- <dd>This indicates that the callee does not make any copies of the pointer
- that outlive the callee itself. This is not a valid attribute for return
- values.</dd>
-
- <dt><tt><b><a name="nest">nest</a></b></tt></dt>
- <dd>This indicates that the pointer parameter can be excised using the
- <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid
- attribute for return values.</dd>
-</dl>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="gc">Garbage Collector Names</a>
-</h3>
-
-<div>
-
-<p>Each function may specify a garbage collector name, which is simply a
- string:</p>
-
-<pre class="doc_code">
-define void @f() gc "name" { ... }
-</pre>
-
-<p>The compiler declares the supported values of <i>name</i>. Specifying a
- collector which will cause the compiler to alter its output in order to
- support the named garbage collection algorithm.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="fnattrs">Function Attributes</a>
-</h3>
-
-<div>
-
-<p>Function attributes are set to communicate additional information about a
- function. Function attributes are considered to be part of the function, not
- of the function type, so functions with different function attributes can
- have the same function type.</p>
-
-<p>Function attributes are simple keywords that follow the type specified. If
- multiple attributes are needed, they are space separated. For example:</p>
-
-<pre class="doc_code">
-define void @f() noinline { ... }
-define void @f() alwaysinline { ... }
-define void @f() alwaysinline optsize { ... }
-define void @f() optsize { ... }
-</pre>
-
-<dl>
- <dt><tt><b>address_safety</b></tt></dt>
- <dd>This attribute indicates that the address safety analysis
- is enabled for this function. </dd>
-
- <dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt>
- <dd>This attribute indicates that, when emitting the prologue and epilogue,
- the backend should forcibly align the stack pointer. Specify the
- desired alignment, which must be a power of two, in parentheses.
-
- <dt><tt><b>alwaysinline</b></tt></dt>
- <dd>This attribute indicates that the inliner should attempt to inline this
- function into callers whenever possible, ignoring any active inlining size
- threshold for this caller.</dd>
-
- <dt><tt><b>nonlazybind</b></tt></dt>
- <dd>This attribute suppresses lazy symbol binding for the function. This
- may make calls to the function faster, at the cost of extra program
- startup time if the function is not called during program startup.</dd>
-
- <dt><tt><b>inlinehint</b></tt></dt>
- <dd>This attribute indicates that the source code contained a hint that inlining
- this function is desirable (such as the "inline" keyword in C/C++). It
- is just a hint; it imposes no requirements on the inliner.</dd>
-
- <dt><tt><b>naked</b></tt></dt>
- <dd>This attribute disables prologue / epilogue emission for the function.
- This can have very system-specific consequences.</dd>
-
- <dt><tt><b>noimplicitfloat</b></tt></dt>
- <dd>This attributes disables implicit floating point instructions.</dd>
-
- <dt><tt><b>noinline</b></tt></dt>
- <dd>This attribute indicates that the inliner should never inline this
- function in any situation. This attribute may not be used together with
- the <tt>alwaysinline</tt> attribute.</dd>
-
- <dt><tt><b>noredzone</b></tt></dt>
- <dd>This attribute indicates that the code generator should not use a red
- zone, even if the target-specific ABI normally permits it.</dd>
-
- <dt><tt><b>noreturn</b></tt></dt>
- <dd>This function attribute indicates that the function never returns
- normally. This produces undefined behavior at runtime if the function
- ever does dynamically return.</dd>
-
- <dt><tt><b>nounwind</b></tt></dt>
- <dd>This function attribute indicates that the function never returns with an
- unwind or exceptional control flow. If the function does unwind, its
- runtime behavior is undefined.</dd>
-
- <dt><tt><b>optsize</b></tt></dt>
- <dd>This attribute suggests that optimization passes and code generator passes
- make choices that keep the code size of this function low, and otherwise
- do optimizations specifically to reduce code size.</dd>
-
- <dt><tt><b>readnone</b></tt></dt>
- <dd>This attribute indicates that the function computes its result (or decides
- to unwind an exception) based strictly on its arguments, without
- dereferencing any pointer arguments or otherwise accessing any mutable
- state (e.g. memory, control registers, etc) visible to caller functions.
- It does not write through any pointer arguments
- (including <tt><a href="#byval">byval</a></tt> arguments) and never
- changes any state visible to callers. This means that it cannot unwind
- exceptions by calling the <tt>C++</tt> exception throwing methods.</dd>
-
- <dt><tt><b><a name="readonly">readonly</a></b></tt></dt>
- <dd>This attribute indicates that the function does not write through any
- pointer arguments (including <tt><a href="#byval">byval</a></tt>
- arguments) or otherwise modify any state (e.g. memory, control registers,
- etc) visible to caller functions. It may dereference pointer arguments
- and read state that may be set in the caller. A readonly function always
- returns the same value (or unwinds an exception identically) when called
- with the same set of arguments and global state. It cannot unwind an
- exception by calling the <tt>C++</tt> exception throwing methods.</dd>
-
- <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt>
- <dd>This attribute indicates that this function can return twice. The
- C <code>setjmp</code> is an example of such a function. The compiler
- disables some optimizations (like tail calls) in the caller of these
- functions.</dd>
-
- <dt><tt><b><a name="ssp">ssp</a></b></tt></dt>
- <dd>This attribute indicates that the function should emit a stack smashing
- protector. It is in the form of a "canary"—a random value placed on
- the stack before the local variables that's checked upon return from the
- function to see if it has been overwritten. A heuristic is used to
- determine if a function needs stack protectors or not.<br>
-<br>
- If a function that has an <tt>ssp</tt> attribute is inlined into a
- function that doesn't have an <tt>ssp</tt> attribute, then the resulting
- function will have an <tt>ssp</tt> attribute.</dd>
-
- <dt><tt><b>sspreq</b></tt></dt>
- <dd>This attribute indicates that the function should <em>always</em> emit a
- stack smashing protector. This overrides
- the <tt><a href="#ssp">ssp</a></tt> function attribute.<br>
-<br>
- If a function that has an <tt>sspreq</tt> attribute is inlined into a
- function that doesn't have an <tt>sspreq</tt> attribute or which has
- an <tt>ssp</tt> attribute, then the resulting function will have
- an <tt>sspreq</tt> attribute.</dd>
-
- <dt><tt><b><a name="uwtable">uwtable</a></b></tt></dt>
- <dd>This attribute indicates that the ABI being targeted requires that
- an unwind table entry be produce for this function even if we can
- show that no exceptions passes by it. This is normally the case for
- the ELF x86-64 abi, but it can be disabled for some compilation
- units.</dd>
-</dl>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="moduleasm">Module-Level Inline Assembly</a>
-</h3>
-
-<div>
-
-<p>Modules may contain "module-level inline asm" blocks, which corresponds to
- the GCC "file scope inline asm" blocks. These blocks are internally
- concatenated by LLVM and treated as a single unit, but may be separated in
- the <tt>.ll</tt> file if desired. The syntax is very simple:</p>
-
-<pre class="doc_code">
-module asm "inline asm code goes here"
-module asm "more can go here"
-</pre>
-
-<p>The strings can contain any character by escaping non-printable characters.
- The escape sequence used is simply "\xx" where "xx" is the two digit hex code
- for the number.</p>
-
-<p>The inline asm code is simply printed to the machine code .s file when
- assembly code is generated.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="datalayout">Data Layout</a>
-</h3>
-
-<div>
-
-<p>A module may specify a target specific data layout string that specifies how
- data is to be laid out in memory. The syntax for the data layout is
- simply:</p>
-
-<pre class="doc_code">
-target datalayout = "<i>layout specification</i>"
-</pre>
-
-<p>The <i>layout specification</i> consists of a list of specifications
- separated by the minus sign character ('-'). Each specification starts with
- a letter and may include other information after the letter to define some
- aspect of the data layout. The specifications accepted are as follows:</p>
-
-<dl>
- <dt><tt>E</tt></dt>
- <dd>Specifies that the target lays out data in big-endian form. That is, the
- bits with the most significance have the lowest address location.</dd>
-
- <dt><tt>e</tt></dt>
- <dd>Specifies that the target lays out data in little-endian form. That is,
- the bits with the least significance have the lowest address
- location.</dd>
-
- <dt><tt>S<i>size</i></tt></dt>
- <dd>Specifies the natural alignment of the stack in bits. Alignment promotion
- of stack variables is limited to the natural stack alignment to avoid
- dynamic stack realignment. The stack alignment must be a multiple of
- 8-bits. If omitted, the natural stack alignment defaults to "unspecified",
- which does not prevent any alignment promotions.</dd>
-
- <dt><tt>p[n]:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
- <i>preferred</i> alignments for address space <i>n</i>. All sizes are in
- bits. Specifying the <i>pref</i> alignment is optional. If omitted, the
- preceding <tt>:</tt> should be omitted too. The address space,
- <i>n</i> is optional, and if not specified, denotes the default address
- space 0. The value of <i>n</i> must be in the range [1,2^23).</dd>
-
- <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the alignment for an integer type of a given bit
- <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
-
- <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the alignment for a vector type of a given bit
- <i>size</i>.</dd>
-
- <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the alignment for a floating point type of a given bit
- <i>size</i>. Only values of <i>size</i> that are supported by the target
- will work. 32 (float) and 64 (double) are supported on all targets;
- 80 or 128 (different flavors of long double) are also supported on some
- targets.
-
- <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the alignment for an aggregate type of a given bit
- <i>size</i>.</dd>
-
- <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
- <dd>This specifies the alignment for a stack object of a given bit
- <i>size</i>.</dd>
-
- <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt>
- <dd>This specifies a set of native integer widths for the target CPU
- in bits. For example, it might contain "n32" for 32-bit PowerPC,
- "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64. Elements of
- this set are considered to support most general arithmetic
- operations efficiently.</dd>
-</dl>
-
-<p>When constructing the data layout for a given target, LLVM starts with a
- default set of specifications which are then (possibly) overridden by the
- specifications in the <tt>datalayout</tt> keyword. The default specifications
- are given in this list:</p>
-
-<ul>
- <li><tt>E</tt> - big endian</li>
- <li><tt>p:64:64:64</tt> - 64-bit pointers with 64-bit alignment</li>
- <li><tt>p1:32:32:32</tt> - 32-bit pointers with 32-bit alignment for
- address space 1</li>
- <li><tt>p2:16:32:32</tt> - 16-bit pointers with 32-bit alignment for
- address space 2</li>
- <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
- <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
- <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
- <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li>
- <li><tt>i64:32:64</tt> - i64 has ABI alignment of 32-bits but preferred
- alignment of 64-bits</li>
- <li><tt>f32:32:32</tt> - float is 32-bit aligned</li>
- <li><tt>f64:64:64</tt> - double is 64-bit aligned</li>
- <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li>
- <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li>
- <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li>
- <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li>
-</ul>
-
-<p>When LLVM is determining the alignment for a given type, it uses the
- following rules:</p>
-
-<ol>
- <li>If the type sought is an exact match for one of the specifications, that
- specification is used.</li>
-
- <li>If no match is found, and the type sought is an integer type, then the
- smallest integer type that is larger than the bitwidth of the sought type
- is used. If none of the specifications are larger than the bitwidth then
- the largest integer type is used. For example, given the default
- specifications above, the i7 type will use the alignment of i8 (next
- largest) while both i65 and i256 will use the alignment of i64 (largest
- specified).</li>
-
- <li>If no match is found, and the type sought is a vector type, then the
- largest vector type that is smaller than the sought vector type will be
- used as a fall back. This happens because <128 x double> can be
- implemented in terms of 64 <2 x double>, for example.</li>
-</ol>
-
-<p>The function of the data layout string may not be what you expect. Notably,
- this is not a specification from the frontend of what alignment the code
- generator should use.</p>
-
-<p>Instead, if specified, the target data layout is required to match what the
- ultimate <em>code generator</em> expects. This string is used by the
- mid-level optimizers to
- improve code, and this only works if it matches what the ultimate code
- generator uses. If you would like to generate IR that does not embed this
- target-specific detail into the IR, then you don't have to specify the
- string. This will disable some optimizations that require precise layout
- information, but this also prevents those optimizations from introducing
- target specificity into the IR.</p>
-
-
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="pointeraliasing">Pointer Aliasing Rules</a>
-</h3>
-
-<div>
-
-<p>Any memory access must be done through a pointer value associated
-with an address range of the memory access, otherwise the behavior
-is undefined. Pointer values are associated with address ranges
-according to the following rules:</p>
-
-<ul>
- <li>A pointer value is associated with the addresses associated with
- any value it is <i>based</i> on.
- <li>An address of a global variable is associated with the address
- range of the variable's storage.</li>
- <li>The result value of an allocation instruction is associated with
- the address range of the allocated storage.</li>
- <li>A null pointer in the default address-space is associated with
- no address.</li>
- <li>An integer constant other than zero or a pointer value returned
- from a function not defined within LLVM may be associated with address
- ranges allocated through mechanisms other than those provided by
- LLVM. Such ranges shall not overlap with any ranges of addresses
- allocated by mechanisms provided by LLVM.</li>
-</ul>
-
-<p>A pointer value is <i>based</i> on another pointer value according
- to the following rules:</p>
-
-<ul>
- <li>A pointer value formed from a
- <tt><a href="#i_getelementptr">getelementptr</a></tt> operation
- is <i>based</i> on the first operand of the <tt>getelementptr</tt>.</li>
- <li>The result value of a
- <tt><a href="#i_bitcast">bitcast</a></tt> is <i>based</i> on the operand
- of the <tt>bitcast</tt>.</li>
- <li>A pointer value formed by an
- <tt><a href="#i_inttoptr">inttoptr</a></tt> is <i>based</i> on all
- pointer values that contribute (directly or indirectly) to the
- computation of the pointer's value.</li>
- <li>The "<i>based</i> on" relationship is transitive.</li>
-</ul>
-
-<p>Note that this definition of <i>"based"</i> is intentionally
- similar to the definition of <i>"based"</i> in C99, though it is
- slightly weaker.</p>
-
-<p>LLVM IR does not associate types with memory. The result type of a
-<tt><a href="#i_load">load</a></tt> merely indicates the size and
-alignment of the memory from which to load, as well as the
-interpretation of the value. The first operand type of a
-<tt><a href="#i_store">store</a></tt> similarly only indicates the size
-and alignment of the store.</p>
-
-<p>Consequently, type-based alias analysis, aka TBAA, aka
-<tt>-fstrict-aliasing</tt>, is not applicable to general unadorned
-LLVM IR. <a href="#metadata">Metadata</a> may be used to encode
-additional information which specialized optimization passes may use
-to implement type-based alias analysis.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="volatile">Volatile Memory Accesses</a>
-</h3>
-
-<div>
-
-<p>Certain memory accesses, such as <a href="#i_load"><tt>load</tt></a>s, <a
-href="#i_store"><tt>store</tt></a>s, and <a
-href="#int_memcpy"><tt>llvm.memcpy</tt></a>s may be marked <tt>volatile</tt>.
-The optimizers must not change the number of volatile operations or change their
-order of execution relative to other volatile operations. The optimizers
-<i>may</i> change the order of volatile operations relative to non-volatile
-operations. This is not Java's "volatile" and has no cross-thread
-synchronization behavior.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="memmodel">Memory Model for Concurrent Operations</a>
-</h3>
-
-<div>
-
-<p>The LLVM IR does not define any way to start parallel threads of execution
-or to register signal handlers. Nonetheless, there are platform-specific
-ways to create them, and we define LLVM IR's behavior in their presence. This
-model is inspired by the C++0x memory model.</p>
-
-<p>For a more informal introduction to this model, see the
-<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.
-
-<p>We define a <i>happens-before</i> partial order as the least partial order
-that</p>
-<ul>
- <li>Is a superset of single-thread program order, and</li>
- <li>When a <i>synchronizes-with</i> <tt>b</tt>, includes an edge from
- <tt>a</tt> to <tt>b</tt>. <i>Synchronizes-with</i> pairs are introduced
- by platform-specific techniques, like pthread locks, thread
- creation, thread joining, etc., and by atomic instructions.
- (See also <a href="#ordering">Atomic Memory Ordering Constraints</a>).
- </li>
-</ul>
-
-<p>Note that program order does not introduce <i>happens-before</i> edges
-between a thread and signals executing inside that thread.</p>
-
-<p>Every (defined) read operation (load instructions, memcpy, atomic
-loads/read-modify-writes, etc.) <var>R</var> reads a series of bytes written by
-(defined) write operations (store instructions, atomic
-stores/read-modify-writes, memcpy, etc.). For the purposes of this section,
-initialized globals are considered to have a write of the initializer which is
-atomic and happens before any other read or write of the memory in question.
-For each byte of a read <var>R</var>, <var>R<sub>byte</sub></var> may see
-any write to the same byte, except:</p>
-
-<ul>
- <li>If <var>write<sub>1</sub></var> happens before
- <var>write<sub>2</sub></var>, and <var>write<sub>2</sub></var> happens
- before <var>R<sub>byte</sub></var>, then <var>R<sub>byte</sub></var>
- does not see <var>write<sub>1</sub></var>.
- <li>If <var>R<sub>byte</sub></var> happens before
- <var>write<sub>3</sub></var>, then <var>R<sub>byte</sub></var> does not
- see <var>write<sub>3</sub></var>.
-</ul>
-
-<p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows:
-<ul>
- <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile
- is supposed to give guarantees which can support
- <code>sig_atomic_t</code> in C/C++, and may be used for accesses to
- addresses which do not behave like normal memory. It does not generally
- provide cross-thread synchronization.)
- <li>Otherwise, if there is no write to the same byte that happens before
- <var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns
- <tt>undef</tt> for that byte.
- <li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write,
- <var>R<sub>byte</sub></var> returns the value written by that
- write.</li>
- <li>Otherwise, if <var>R</var> is atomic, and all the writes
- <var>R<sub>byte</sub></var> may see are atomic, it chooses one of the
- values written. See the <a href="#ordering">Atomic Memory Ordering
- Constraints</a> section for additional constraints on how the choice
- is made.
- <li>Otherwise <var>R<sub>byte</sub></var> returns <tt>undef</tt>.</li>
-</ul>
-
-<p><var>R</var> returns the value composed of the series of bytes it read.
-This implies that some bytes within the value may be <tt>undef</tt>
-<b>without</b> the entire value being <tt>undef</tt>. Note that this only
-defines the semantics of the operation; it doesn't mean that targets will
-emit more than one instruction to read the series of bytes.</p>
-
-<p>Note that in cases where none of the atomic intrinsics are used, this model
-places only one restriction on IR transformations on top of what is required
-for single-threaded execution: introducing a store to a byte which might not
-otherwise be stored is not allowed in general. (Specifically, in the case
-where another thread might write to and read from an address, introducing a
-store can change a load that may see exactly one write into a load that may
-see multiple writes.)</p>
-
-<!-- FIXME: This model assumes all targets where concurrency is relevant have
-a byte-size store which doesn't affect adjacent bytes. As far as I can tell,
-none of the backends currently in the tree fall into this category; however,
-there might be targets which care. If there are, we want a paragraph
-like the following:
-
-Targets may specify that stores narrower than a certain width are not
-available; on such a target, for the purposes of this model, treat any
-non-atomic write with an alignment or width less than the minimum width
-as if it writes to the relevant surrounding bytes.
--->
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="ordering">Atomic Memory Ordering Constraints</a>
-</h3>
-
-<div>
-
-<p>Atomic instructions (<a href="#i_cmpxchg"><code>cmpxchg</code></a>,
-<a href="#i_atomicrmw"><code>atomicrmw</code></a>,
-<a href="#i_fence"><code>fence</code></a>,
-<a href="#i_load"><code>atomic load</code></a>, and
-<a href="#i_store"><code>atomic store</code></a>) take an ordering parameter
-that determines which other atomic instructions on the same address they
-<i>synchronize with</i>. These semantics are borrowed from Java and C++0x,
-but are somewhat more colloquial. If these descriptions aren't precise enough,
-check those specs (see spec references in the
-<a href="Atomics.html#introduction">atomics guide</a>).
-<a href="#i_fence"><code>fence</code></a> instructions
-treat these orderings somewhat differently since they don't take an address.
-See that instruction's documentation for details.</p>
-
-<p>For a simpler introduction to the ordering constraints, see the
-<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p>
-
-<dl>
-<dt><code>unordered</code></dt>
-<dd>The set of values that can be read is governed by the happens-before
-partial order. A value cannot be read unless some operation wrote it.
-This is intended to provide a guarantee strong enough to model Java's
-non-volatile shared variables. This ordering cannot be specified for
-read-modify-write operations; it is not strong enough to make them atomic
-in any interesting way.</dd>
-<dt><code>monotonic</code></dt>
-<dd>In addition to the guarantees of <code>unordered</code>, there is a single
-total order for modifications by <code>monotonic</code> operations on each
-address. All modification orders must be compatible with the happens-before
-order. There is no guarantee that the modification orders can be combined to
-a global total order for the whole program (and this often will not be
-possible). The read in an atomic read-modify-write operation
-(<a href="#i_cmpxchg"><code>cmpxchg</code></a> and
-<a href="#i_atomicrmw"><code>atomicrmw</code></a>)
-reads the value in the modification order immediately before the value it
-writes. If one atomic read happens before another atomic read of the same
-address, the later read must see the same value or a later value in the
-address's modification order. This disallows reordering of
-<code>monotonic</code> (or stronger) operations on the same address. If an
-address is written <code>monotonic</code>ally by one thread, and other threads
-<code>monotonic</code>ally read that address repeatedly, the other threads must
-eventually see the write. This corresponds to the C++0x/C1x
-<code>memory_order_relaxed</code>.</dd>
-<dt><code>acquire</code></dt>
-<dd>In addition to the guarantees of <code>monotonic</code>,
-a <i>synchronizes-with</i> edge may be formed with a <code>release</code>
-operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd>
-<dt><code>release</code></dt>
-<dd>In addition to the guarantees of <code>monotonic</code>, if this operation
-writes a value which is subsequently read by an <code>acquire</code> operation,
-it <i>synchronizes-with</i> that operation. (This isn't a complete
-description; see the C++0x definition of a release sequence.) This corresponds
-to the C++0x/C1x <code>memory_order_release</code>.</dd>
-<dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an
-<code>acquire</code> and <code>release</code> operation on its address.
-This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd>
-<dt><code>seq_cst</code> (sequentially consistent)</dt><dd>
-<dd>In addition to the guarantees of <code>acq_rel</code>
-(<code>acquire</code> for an operation which only reads, <code>release</code>
-for an operation which only writes), there is a global total order on all
-sequentially-consistent operations on all addresses, which is consistent with
-the <i>happens-before</i> partial order and with the modification orders of
-all the affected addresses. Each sequentially-consistent read sees the last
-preceding write to the same address in this global order. This corresponds
-to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd>
-</dl>
-
-<p id="singlethread">If an atomic operation is marked <code>singlethread</code>,
-it only <i>synchronizes with</i> or participates in modification and seq_cst
-total orderings with other operations running in the same thread (for example,
-in signal handlers).</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="fastmath">Fast-Math Flags</a>
-</h3>
-
-<div>
-
-<p> LLVM IR floating-point binary ops (<a href="#i_fadd"><code>fadd</code></a>,
-<a href="#i_fsub"><code>fsub</code></a>, <a
- href="#i_fmul"><code>fmul</code></a>, <a href="#i_fdiv"><code>fdiv</code></a>,
-<a href="#i_frem"><code>frem</code></a>) have the following flags
-that can set to enable otherwise unsafe floating point operations</p>
-
-<dt><code>nnan</dt></code>
-<dd>
- No NaNs - Allow optimizations to assume the arguments and result are not
-NaN. Such optimizations are required to retain defined behavior over NaNs, but
-the value of the result is undefined.
-</dd>
-
-<dt><code>ninf</code></dt>
-<dd>
- No Infs - Allow optimizations to assume the arguments and result are not
-+/-Inf. Such optimizations are required to retain defined behavior over +/-Inf,
-but the value of the result is undefined.
-</dd>
-
-<dt><code>nsz</code></dt>
-<dd>
- No Signed Zeros - Allow optimizations to treat the sign of a zero argument or
-result as insignificant.
-</dd>
-
-<dt><code>arcp</code></dt>
-<dd>
- Allow Reciprocal - Allow optimizations to use the reciprocal of an argument
-rather than perform division.
-</dd>
-
-<dt><code>fast</code></TD>
-<dd>
- Fast - Allow algebraically equivalent transformations that may dramatically
-change results in floating point (e.g. reassociate). This flag implies all the
-others.
-</dd>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="typesystem">Type System</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>The LLVM type system is one of the most important features of the
- intermediate representation. Being typed enables a number of optimizations
- to be performed on the intermediate representation directly, without having
- to do extra analyses on the side before the transformation. A strong type
- system makes it easier to read the generated code and enables novel analyses
- and transformations that are not feasible to perform on normal three address
- code representations.</p>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="t_classifications">Type Classifications</a>
-</h3>
-
-<div>
-
-<p>The types fall into a few useful classifications:</p>
-
-<table border="1" cellspacing="0" cellpadding="4">
- <tbody>
- <tr><th>Classification</th><th>Types</th></tr>
- <tr>
- <td><a href="#t_integer">integer</a></td>
- <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td>
- </tr>
- <tr>
- <td><a href="#t_floating">floating point</a></td>
- <td><tt>half, float, double, x86_fp80, fp128, ppc_fp128</tt></td>
- </tr>
- <tr>
- <td><a name="t_firstclass">first class</a></td>
- <td><a href="#t_integer">integer</a>,
- <a href="#t_floating">floating point</a>,
- <a href="#t_pointer">pointer</a>,
- <a href="#t_vector">vector</a>,
- <a href="#t_struct">structure</a>,
- <a href="#t_array">array</a>,
- <a href="#t_label">label</a>,
- <a href="#t_metadata">metadata</a>.
- </td>
- </tr>
- <tr>
- <td><a href="#t_primitive">primitive</a></td>
- <td><a href="#t_label">label</a>,
- <a href="#t_void">void</a>,
- <a href="#t_integer">integer</a>,
- <a href="#t_floating">floating point</a>,
- <a href="#t_x86mmx">x86mmx</a>,
- <a href="#t_metadata">metadata</a>.</td>
- </tr>
- <tr>
- <td><a href="#t_derived">derived</a></td>
- <td><a href="#t_array">array</a>,
- <a href="#t_function">function</a>,
- <a href="#t_pointer">pointer</a>,
- <a href="#t_struct">structure</a>,
- <a href="#t_vector">vector</a>,
- <a href="#t_opaque">opaque</a>.
- </td>
- </tr>
- </tbody>
-</table>
-
-<p>The <a href="#t_firstclass">first class</a> types are perhaps the most
- important. Values of these types are the only ones which can be produced by
- instructions.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="t_primitive">Primitive Types</a>
-</h3>
-
-<div>
-
-<p>The primitive types are the fundamental building blocks of the LLVM
- system.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_integer">Integer Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The integer type is a very simple type that simply specifies an arbitrary
- bit width for the integer type desired. Any bit width from 1 bit to
- 2<sup>23</sup>-1 (about 8 million) can be specified.</p>
-
-<h5>Syntax:</h5>
-<pre>
- iN
-</pre>
-
-<p>The number of bits the integer will occupy is specified by the <tt>N</tt>
- value.</p>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>i1</tt></td>
- <td class="left">a single-bit integer.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i32</tt></td>
- <td class="left">a 32-bit integer.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i1942652</tt></td>
- <td class="left">a really big integer of over 1 million bits.</td>
- </tr>
-</table>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_floating">Floating Point Types</a>
-</h4>
-
-<div>
-
-<table>
- <tbody>
- <tr><th>Type</th><th>Description</th></tr>
- <tr><td><tt>half</tt></td><td>16-bit floating point value</td></tr>
- <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
- <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
- <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr>
- <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr>
- <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr>
- </tbody>
-</table>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_x86mmx">X86mmx Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The x86mmx type represents a value held in an MMX register on an x86 machine. The operations allowed on it are quite limited: parameters and return values, load and store, and bitcast. User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type. There are no arrays, vectors or constants of this type.</p>
-
-<h5>Syntax:</h5>
-<pre>
- x86mmx
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_void">Void Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The void type does not represent any value and has no size.</p>
-
-<h5>Syntax:</h5>
-<pre>
- void
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_label">Label Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The label type represents code labels.</p>
-
-<h5>Syntax:</h5>
-<pre>
- label
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_metadata">Metadata Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The metadata type represents embedded metadata. No derived types may be
- created from metadata except for <a href="#t_function">function</a>
- arguments.
-
-<h5>Syntax:</h5>
-<pre>
- metadata
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="t_derived">Derived Types</a>
-</h3>
-
-<div>
-
-<p>The real power in LLVM comes from the derived types in the system. This is
- what allows a programmer to represent arrays, functions, pointers, and other
- useful types. Each of these types contain one or more element types which
- may be a primitive type, or another derived type. For example, it is
- possible to have a two dimensional array, using an array as the element type
- of another array.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_aggregate">Aggregate Types</a>
-</h4>
-
-<div>
-
-<p>Aggregate Types are a subset of derived types that can contain multiple
- member types. <a href="#t_array">Arrays</a> and
- <a href="#t_struct">structs</a> are aggregate types.
- <a href="#t_vector">Vectors</a> are not considered to be aggregate types.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_array">Array Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The array type is a very simple derived type that arranges elements
- sequentially in memory. The array type requires a size (number of elements)
- and an underlying data type.</p>
-
-<h5>Syntax:</h5>
-<pre>
- [<# elements> x <elementtype>]
-</pre>
-
-<p>The number of elements is a constant integer value; <tt>elementtype</tt> may
- be any type with a size.</p>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>[40 x i32]</tt></td>
- <td class="left">Array of 40 32-bit integer values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>[41 x i32]</tt></td>
- <td class="left">Array of 41 32-bit integer values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>[4 x i8]</tt></td>
- <td class="left">Array of 4 8-bit integer values.</td>
- </tr>
-</table>
-<p>Here are some examples of multidimensional arrays:</p>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>[3 x [4 x i32]]</tt></td>
- <td class="left">3x4 array of 32-bit integer values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>[12 x [10 x float]]</tt></td>
- <td class="left">12x10 array of single precision floating point values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td>
- <td class="left">2x3x4 array of 16-bit integer values.</td>
- </tr>
-</table>
-
-<p>There is no restriction on indexing beyond the end of the array implied by
- a static type (though there are restrictions on indexing beyond the bounds
- of an allocated object in some cases). This means that single-dimension
- 'variable sized array' addressing can be implemented in LLVM with a zero
- length array type. An implementation of 'pascal style arrays' in LLVM could
- use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_function">Function Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The function type can be thought of as a function signature. It consists of
- a return type and a list of formal parameter types. The return type of a
- function type is a first class type or a void type.</p>
-
-<h5>Syntax:</h5>
-<pre>
- <returntype> (<parameter list>)
-</pre>
-
-<p>...where '<tt><parameter list></tt>' is a comma-separated list of type
- specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
- which indicates that the function takes a variable number of arguments.
- Variable argument functions can access their arguments with
- the <a href="#int_varargs">variable argument handling intrinsic</a>
- functions. '<tt><returntype></tt>' is any type except
- <a href="#t_label">label</a>.</p>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>i32 (i32)</tt></td>
- <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
- </td>
- </tr><tr class="layout">
- <td class="left"><tt>float (i16, i32 *) *
- </tt></td>
- <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
- an <tt>i16</tt> and a <a href="#t_pointer">pointer</a> to <tt>i32</tt>,
- returning <tt>float</tt>.
- </td>
- </tr><tr class="layout">
- <td class="left"><tt>i32 (i8*, ...)</tt></td>
- <td class="left">A vararg function that takes at least one
- <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
- which returns an integer. This is the signature for <tt>printf</tt> in
- LLVM.
- </td>
- </tr><tr class="layout">
- <td class="left"><tt>{i32, i32} (i32)</tt></td>
- <td class="left">A function taking an <tt>i32</tt>, returning a
- <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
- </td>
- </tr>
-</table>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_struct">Structure Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The structure type is used to represent a collection of data members together
- in memory. The elements of a structure may be any type that has a size.</p>
-
-<p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>'
- and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field
- with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.
- Structures in registers are accessed using the
- '<tt><a href="#i_extractvalue">extractvalue</a></tt>' and
- '<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p>
-
-<p>Structures may optionally be "packed" structures, which indicate that the
- alignment of the struct is one byte, and that there is no padding between
- the elements. In non-packed structs, padding between field types is inserted
- as defined by the DataLayout string in the module, which is required to match
- what the underlying code generator expects.</p>
-
-<p>Structures can either be "literal" or "identified". A literal structure is
- defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified
- types are always defined at the top level with a name. Literal types are
- uniqued by their contents and can never be recursive or opaque since there is
- no way to write one. Identified types can be recursive, can be opaqued, and are
- never uniqued.
-</p>
-
-<h5>Syntax:</h5>
-<pre>
- %T1 = type { <type list> } <i>; Identified normal struct type</i>
- %T2 = type <{ <type list> }> <i>; Identified packed struct type</i>
-</pre>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>{ i32, i32, i32 }</tt></td>
- <td class="left">A triple of three <tt>i32</tt> values</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>{ float, i32 (i32) * }</tt></td>
- <td class="left">A pair, where the first element is a <tt>float</tt> and the
- second element is a <a href="#t_pointer">pointer</a> to a
- <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
- an <tt>i32</tt>.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt><{ i8, i32 }></tt></td>
- <td class="left">A packed struct known to be 5 bytes in size.</td>
- </tr>
-</table>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_opaque">Opaque Structure Types</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>Opaque structure types are used to represent named structure types that do
- not have a body specified. This corresponds (for example) to the C notion of
- a forward declared structure.</p>
-
-<h5>Syntax:</h5>
-<pre>
- %X = type opaque
- %52 = type opaque
-</pre>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>opaque</tt></td>
- <td class="left">An opaque type.</td>
- </tr>
-</table>
-
-</div>
-
-
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_pointer">Pointer Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>The pointer type is used to specify memory locations.
- Pointers are commonly used to reference objects in memory.</p>
-
-<p>Pointer types may have an optional address space attribute defining the
- numbered address space where the pointed-to object resides. The default
- address space is number zero. The semantics of non-zero address
- spaces are target-specific.</p>
-
-<p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it
- permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p>
-
-<h5>Syntax:</h5>
-<pre>
- <type> *
-</pre>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>[4 x i32]*</tt></td>
- <td class="left">A <a href="#t_pointer">pointer</a> to <a
- href="#t_array">array</a> of four <tt>i32</tt> values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i32 (i32*) *</tt></td>
- <td class="left"> A <a href="#t_pointer">pointer</a> to a <a
- href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an
- <tt>i32</tt>.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i32 addrspace(5)*</tt></td>
- <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value
- that resides in address space #5.</td>
- </tr>
-</table>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="t_vector">Vector Type</a>
-</h4>
-
-<div>
-
-<h5>Overview:</h5>
-<p>A vector type is a simple derived type that represents a vector of elements.
- Vector types are used when multiple primitive data are operated in parallel
- using a single instruction (SIMD). A vector type requires a size (number of
- elements) and an underlying primitive data type. Vector types are considered
- <a href="#t_firstclass">first class</a>.</p>
-
-<h5>Syntax:</h5>
-<pre>
- < <# elements> x <elementtype> >
-</pre>
-
-<p>The number of elements is a constant integer value larger than 0; elementtype
- may be any integer or floating point type, or a pointer to these types.
- Vectors of size zero are not allowed. </p>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt><4 x i32></tt></td>
- <td class="left">Vector of 4 32-bit integer values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt><8 x float></tt></td>
- <td class="left">Vector of 8 32-bit floating-point values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt><2 x i64></tt></td>
- <td class="left">Vector of 2 64-bit integer values.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt><4 x i64*></tt></td>
- <td class="left">Vector of 4 pointers to 64-bit integer values.</td>
- </tr>
-</table>
-
-</div>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="constants">Constants</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>LLVM has several different basic types of constants. This section describes
- them all and their syntax.</p>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="simpleconstants">Simple Constants</a>
-</h3>
-
-<div>
-
-<dl>
- <dt><b>Boolean constants</b></dt>
- <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
- constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd>
-
- <dt><b>Integer constants</b></dt>
- <dd>Standard integers (such as '4') are constants of
- the <a href="#t_integer">integer</a> type. Negative numbers may be used
- with integer types.</dd>
-
- <dt><b>Floating point constants</b></dt>
- <dd>Floating point constants use standard decimal notation (e.g. 123.421),
- exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
- notation (see below). The assembler requires the exact decimal value of a
- floating-point constant. For example, the assembler accepts 1.25 but
- rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point
- constants must have a <a href="#t_floating">floating point</a> type. </dd>
-
- <dt><b>Null pointer constants</b></dt>
- <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
- and must be of <a href="#t_pointer">pointer type</a>.</dd>
-</dl>
-
-<p>The one non-intuitive notation for constants is the hexadecimal form of
- floating point constants. For example, the form '<tt>double
- 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than)
- '<tt>double 4.5e+15</tt>'. The only time hexadecimal floating point
- constants are required (and the only time that they are generated by the
- disassembler) is when a floating point constant must be emitted but it cannot
- be represented as a decimal floating point number in a reasonable number of
- digits. For example, NaN's, infinities, and other special values are
- represented in their IEEE hexadecimal format so that assembly and disassembly
- do not cause any bits to change in the constants.</p>
-
-<p>When using the hexadecimal form, constants of types half, float, and double are
- represented using the 16-digit form shown above (which matches the IEEE754
- representation for double); half and float values must, however, be exactly
- representable as IEE754 half and single precision, respectively.
- Hexadecimal format is always used
- for long double, and there are three forms of long double. The 80-bit format
- used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits.
- The 128-bit format used by PowerPC (two adjacent doubles) is represented
- by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit format
- is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no
- currently supported target uses this format. Long doubles will only work if
- they match the long double format on your target. The IEEE 16-bit format
- (half precision) is represented by <tt>0xH</tt> followed by 4 hexadecimal
- digits. All hexadecimal formats are big-endian (sign bit at the left).</p>
-
-<p>There are no constants of type x86mmx.</p>
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-<a name="aggregateconstants"></a> <!-- old anchor -->
-<a name="complexconstants">Complex Constants</a>
-</h3>
-
-<div>
-
-<p>Complex constants are a (potentially recursive) combination of simple
- constants and smaller complex constants.</p>
-
-<dl>
- <dt><b>Structure constants</b></dt>
- <dd>Structure constants are represented with notation similar to structure
- type definitions (a comma separated list of elements, surrounded by braces
- (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>",
- where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>".
- Structure constants must have <a href="#t_struct">structure type</a>, and
- the number and types of elements must match those specified by the
- type.</dd>
-
- <dt><b>Array constants</b></dt>
- <dd>Array constants are represented with notation similar to array type
- definitions (a comma separated list of elements, surrounded by square
- brackets (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74
- ]</tt>". Array constants must have <a href="#t_array">array type</a>, and
- the number and types of elements must match those specified by the
- type.</dd>
-
- <dt><b>Vector constants</b></dt>
- <dd>Vector constants are represented with notation similar to vector type
- definitions (a comma separated list of elements, surrounded by
- less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32
- 42, i32 11, i32 74, i32 100 ></tt>". Vector constants must
- have <a href="#t_vector">vector type</a>, and the number and types of
- elements must match those specified by the type.</dd>
-
- <dt><b>Zero initialization</b></dt>
- <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
- value to zero of <em>any</em> type, including scalar and
- <a href="#t_aggregate">aggregate</a> types.
- This is often used to avoid having to print large zero initializers
- (e.g. for large arrays) and is always exactly equivalent to using explicit
- zero initializers.</dd>
-
- <dt><b>Metadata node</b></dt>
- <dd>A metadata node is a structure-like constant with
- <a href="#t_metadata">metadata type</a>. For example: "<tt>metadata !{
- i32 0, metadata !"test" }</tt>". Unlike other constants that are meant to
- be interpreted as part of the instruction stream, metadata is a place to
- attach additional information such as debug info.</dd>
-</dl>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="globalconstants">Global Variable and Function Addresses</a>
-</h3>
-
-<div>
-
-<p>The addresses of <a href="#globalvars">global variables</a>
- and <a href="#functionstructure">functions</a> are always implicitly valid
- (link-time) constants. These constants are explicitly referenced when
- the <a href="#identifiers">identifier for the global</a> is used and always
- have <a href="#t_pointer">pointer</a> type. For example, the following is a
- legal LLVM file:</p>
-
-<pre class="doc_code">
-@X = global i32 17
-@Y = global i32 42
-@Z = global [2 x i32*] [ i32* @X, i32* @Y ]
-</pre>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="undefvalues">Undefined Values</a>
-</h3>
-
-<div>
-
-<p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
- indicates that the user of the value may receive an unspecified bit-pattern.
- Undefined values may be of any type (other than '<tt>label</tt>'
- or '<tt>void</tt>') and be used anywhere a constant is permitted.</p>
-
-<p>Undefined values are useful because they indicate to the compiler that the
- program is well defined no matter what value is used. This gives the
- compiler more freedom to optimize. Here are some examples of (potentially
- surprising) transformations that are valid (in pseudo IR):</p>
-
-
-<pre class="doc_code">
- %A = add %X, undef
- %B = sub %X, undef
- %C = xor %X, undef
-Safe:
- %A = undef
- %B = undef
- %C = undef
-</pre>
-
-<p>This is safe because all of the output bits are affected by the undef bits.
- Any output bit can have a zero or one depending on the input bits.</p>
-
-<pre class="doc_code">
- %A = or %X, undef
- %B = and %X, undef
-Safe:
- %A = -1
- %B = 0
-Unsafe:
- %A = undef
- %B = undef
-</pre>
-
-<p>These logical operations have bits that are not always affected by the input.
- For example, if <tt>%X</tt> has a zero bit, then the output of the
- '<tt>and</tt>' operation will always be a zero for that bit, no matter what
- the corresponding bit from the '<tt>undef</tt>' is. As such, it is unsafe to
- optimize or assume that the result of the '<tt>and</tt>' is '<tt>undef</tt>'.
- However, it is safe to assume that all bits of the '<tt>undef</tt>' could be
- 0, and optimize the '<tt>and</tt>' to 0. Likewise, it is safe to assume that
- all the bits of the '<tt>undef</tt>' operand to the '<tt>or</tt>' could be
- set, allowing the '<tt>or</tt>' to be folded to -1.</p>
-
-<pre class="doc_code">
- %A = select undef, %X, %Y
- %B = select undef, 42, %Y
- %C = select %X, %Y, undef
-Safe:
- %A = %X (or %Y)
- %B = 42 (or %Y)
- %C = %Y
-Unsafe:
- %A = undef
- %B = undef
- %C = undef
-</pre>
-
-<p>This set of examples shows that undefined '<tt>select</tt>' (and conditional
- branch) conditions can go <em>either way</em>, but they have to come from one
- of the two operands. In the <tt>%A</tt> example, if <tt>%X</tt> and
- <tt>%Y</tt> were both known to have a clear low bit, then <tt>%A</tt> would
- have to have a cleared low bit. However, in the <tt>%C</tt> example, the
- optimizer is allowed to assume that the '<tt>undef</tt>' operand could be the
- same as <tt>%Y</tt>, allowing the whole '<tt>select</tt>' to be
- eliminated.</p>
-
-<pre class="doc_code">
- %A = xor undef, undef
-
- %B = undef
- %C = xor %B, %B
-
- %D = undef
- %E = icmp lt %D, 4
- %F = icmp gte %D, 4
-
-Safe:
- %A = undef
- %B = undef
- %C = undef
- %D = undef
- %E = undef
- %F = undef
-</pre>
-
-<p>This example points out that two '<tt>undef</tt>' operands are not
- necessarily the same. This can be surprising to people (and also matches C
- semantics) where they assume that "<tt>X^X</tt>" is always zero, even
- if <tt>X</tt> is undefined. This isn't true for a number of reasons, but the
- short answer is that an '<tt>undef</tt>' "variable" can arbitrarily change
- its value over its "live range". This is true because the variable doesn't
- actually <em>have a live range</em>. Instead, the value is logically read
- from arbitrary registers that happen to be around when needed, so the value
- is not necessarily consistent over time. In fact, <tt>%A</tt> and <tt>%C</tt>
- need to have the same semantics or the core LLVM "replace all uses with"
- concept would not hold.</p>
-
-<pre class="doc_code">
- %A = fdiv undef, %X
- %B = fdiv %X, undef
-Safe:
- %A = undef
-b: unreachable
-</pre>
-
-<p>These examples show the crucial difference between an <em>undefined
- value</em> and <em>undefined behavior</em>. An undefined value (like
- '<tt>undef</tt>') is allowed to have an arbitrary bit-pattern. This means that
- the <tt>%A</tt> operation can be constant folded to '<tt>undef</tt>', because
- the '<tt>undef</tt>' could be an SNaN, and <tt>fdiv</tt> is not (currently)
- defined on SNaN's. However, in the second example, we can make a more
- aggressive assumption: because the <tt>undef</tt> is allowed to be an
- arbitrary value, we are allowed to assume that it could be zero. Since a
- divide by zero has <em>undefined behavior</em>, we are allowed to assume that
- the operation does not execute at all. This allows us to delete the divide and
- all code after it. Because the undefined operation "can't happen", the
- optimizer can assume that it occurs in dead code.</p>
-
-<pre class="doc_code">
-a: store undef -> %X
-b: store %X -> undef
-Safe:
-a: <deleted>
-b: unreachable
-</pre>
-
-<p>These examples reiterate the <tt>fdiv</tt> example: a store <em>of</em> an
- undefined value can be assumed to not have any effect; we can assume that the
- value is overwritten with bits that happen to match what was already there.
- However, a store <em>to</em> an undefined location could clobber arbitrary
- memory, therefore, it has undefined behavior.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="poisonvalues">Poison Values</a>
-</h3>
-
-<div>
-
-<p>Poison values are similar to <a href="#undefvalues">undef values</a>, however
- they also represent the fact that an instruction or constant expression which
- cannot evoke side effects has nevertheless detected a condition which results
- in undefined behavior.</p>
-
-<p>There is currently no way of representing a poison value in the IR; they
- only exist when produced by operations such as
- <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p>
-
-<p>Poison value behavior is defined in terms of value <i>dependence</i>:</p>
-
-<ul>
-<li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
- their operands.</li>
-
-<li><a href="#i_phi"><tt>Phi</tt></a> nodes depend on the operand corresponding
- to their dynamic predecessor basic block.</li>
-
-<li>Function arguments depend on the corresponding actual argument values in
- the dynamic callers of their functions.</li>
-
-<li><a href="#i_call"><tt>Call</tt></a> instructions depend on the
- <a href="#i_ret"><tt>ret</tt></a> instructions that dynamically transfer
- control back to them.</li>
-
-<li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the
- <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_resume"><tt>resume</tt></a>,
- or exception-throwing call instructions that dynamically transfer control
- back to them.</li>
-
-<li>Non-volatile loads and stores depend on the most recent stores to all of the
- referenced memory addresses, following the order in the IR
- (including loads and stores implied by intrinsics such as
- <a href="#int_memcpy"><tt>@llvm.memcpy</tt></a>.)</li>
-
-<!-- TODO: In the case of multiple threads, this only applies if the store
- "happens-before" the load or store. -->
-
-<!-- TODO: floating-point exception state -->
-
-<li>An instruction with externally visible side effects depends on the most
- recent preceding instruction with externally visible side effects, following
- the order in the IR. (This includes
- <a href="#volatile">volatile operations</a>.)</li>
-
-<li>An instruction <i>control-depends</i> on a
- <a href="#terminators">terminator instruction</a>
- if the terminator instruction has multiple successors and the instruction
- is always executed when control transfers to one of the successors, and
- may not be executed when control is transferred to another.</li>
-
-<li>Additionally, an instruction also <i>control-depends</i> on a terminator
- instruction if the set of instructions it otherwise depends on would be
- different if the terminator had transferred control to a different
- successor.</li>
-
-<li>Dependence is transitive.</li>
-
-</ul>
-
-<p>Poison Values have the same behavior as <a href="#undefvalues">undef values</a>,
- with the additional affect that any instruction which has a <i>dependence</i>
- on a poison value has undefined behavior.</p>
-
-<p>Here are some examples:</p>
-
-<pre class="doc_code">
-entry:
- %poison = sub nuw i32 0, 1 ; Results in a poison value.
- %still_poison = and i32 %poison, 0 ; 0, but also poison.
- %poison_yet_again = getelementptr i32* @h, i32 %still_poison
- store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned
-
- store i32 %poison, i32* @g ; Poison value stored to memory.
- %poison2 = load i32* @g ; Poison value loaded back from memory.
-
- store volatile i32 %poison, i32* @g ; External observation; undefined behavior.
-
- %narrowaddr = bitcast i32* @g to i16*
- %wideaddr = bitcast i32* @g to i64*
- %poison3 = load i16* %narrowaddr ; Returns a poison value.
- %poison4 = load i64* %wideaddr ; Returns a poison value.
-
- %cmp = icmp slt i32 %poison, 0 ; Returns a poison value.
- br i1 %cmp, label %true, label %end ; Branch to either destination.
-
-true:
- store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so
- ; it has undefined behavior.
- br label %end
-
-end:
- %p = phi i32 [ 0, %entry ], [ 1, %true ]
- ; Both edges into this PHI are
- ; control-dependent on %cmp, so this
- ; always results in a poison value.
-
- store volatile i32 0, i32* @g ; This would depend on the store in %true
- ; if %cmp is true, or the store in %entry
- ; otherwise, so this is undefined behavior.
-
- br i1 %cmp, label %second_true, label %second_end
- ; The same branch again, but this time the
- ; true block doesn't have side effects.
-
-second_true:
- ; No side effects!
- ret void
-
-second_end:
- store volatile i32 0, i32* @g ; This time, the instruction always depends
- ; on the store in %end. Also, it is
- ; control-equivalent to %end, so this is
- ; well-defined (ignoring earlier undefined
- ; behavior in this example).
-</pre>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="blockaddress">Addresses of Basic Blocks</a>
-</h3>
-
-<div>
-
-<p><b><tt>blockaddress(@function, %block)</tt></b></p>
-
-<p>The '<tt>blockaddress</tt>' constant computes the address of the specified
- basic block in the specified function, and always has an i8* type. Taking
- the address of the entry block is illegal.</p>
-
-<p>This value only has defined behavior when used as an operand to the
- '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction, or for
- comparisons against null. Pointer equality tests between labels addresses
- results in undefined behavior — though, again, comparison against null
- is ok, and no label is equal to the null pointer. This may be passed around
- as an opaque pointer sized value as long as the bits are not inspected. This
- allows <tt>ptrtoint</tt> and arithmetic to be performed on these values so
- long as the original value is reconstituted before the <tt>indirectbr</tt>
- instruction.</p>
-
-<p>Finally, some targets may provide defined semantics when using the value as
- the operand to an inline assembly, but that is target specific.</p>
-
-</div>
-
-
-<!-- ======================================================================= -->
-<h3>
- <a name="constantexprs">Constant Expressions</a>
-</h3>
-
-<div>
-
-<p>Constant expressions are used to allow expressions involving other constants
- to be used as constants. Constant expressions may be of
- any <a href="#t_firstclass">first class</a> type and may involve any LLVM
- operation that does not have side effects (e.g. load and call are not
- supported). The following is the syntax for constant expressions:</p>
-
-<dl>
- <dt><b><tt>trunc (CST to TYPE)</tt></b></dt>
- <dd>Truncate a constant to another type. The bit size of CST must be larger
- than the bit size of TYPE. Both types must be integers.</dd>
-
- <dt><b><tt>zext (CST to TYPE)</tt></b></dt>
- <dd>Zero extend a constant to another type. The bit size of CST must be
- smaller than the bit size of TYPE. Both types must be integers.</dd>
-
- <dt><b><tt>sext (CST to TYPE)</tt></b></dt>
- <dd>Sign extend a constant to another type. The bit size of CST must be
- smaller than the bit size of TYPE. Both types must be integers.</dd>
-
- <dt><b><tt>fptrunc (CST to TYPE)</tt></b></dt>
- <dd>Truncate a floating point constant to another floating point type. The
- size of CST must be larger than the size of TYPE. Both types must be
- floating point.</dd>
-
- <dt><b><tt>fpext (CST to TYPE)</tt></b></dt>
- <dd>Floating point extend a constant to another type. The size of CST must be
- smaller or equal to the size of TYPE. Both types must be floating
- point.</dd>
-
- <dt><b><tt>fptoui (CST to TYPE)</tt></b></dt>
- <dd>Convert a floating point constant to the corresponding unsigned integer
- constant. TYPE must be a scalar or vector integer type. CST must be of
- scalar or vector floating point type. Both CST and TYPE must be scalars,
- or vectors of the same number of elements. If the value won't fit in the
- integer type, the results are undefined.</dd>
-
- <dt><b><tt>fptosi (CST to TYPE)</tt></b></dt>
- <dd>Convert a floating point constant to the corresponding signed integer
- constant. TYPE must be a scalar or vector integer type. CST must be of
- scalar or vector floating point type. Both CST and TYPE must be scalars,
- or vectors of the same number of elements. If the value won't fit in the
- integer type, the results are undefined.</dd>
-
- <dt><b><tt>uitofp (CST to TYPE)</tt></b></dt>
- <dd>Convert an unsigned integer constant to the corresponding floating point
- constant. TYPE must be a scalar or vector floating point type. CST must be
- of scalar or vector integer type. Both CST and TYPE must be scalars, or
- vectors of the same number of elements. If the value won't fit in the
- floating point type, the results are undefined.</dd>
-
- <dt><b><tt>sitofp (CST to TYPE)</tt></b></dt>
- <dd>Convert a signed integer constant to the corresponding floating point
- constant. TYPE must be a scalar or vector floating point type. CST must be
- of scalar or vector integer type. Both CST and TYPE must be scalars, or
- vectors of the same number of elements. If the value won't fit in the
- floating point type, the results are undefined.</dd>
-
- <dt><b><tt>ptrtoint (CST to TYPE)</tt></b></dt>
- <dd>Convert a pointer typed constant to the corresponding integer constant
- <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer
- type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to
- make it fit in <tt>TYPE</tt>.</dd>
-
- <dt><b><tt>inttoptr (CST to TYPE)</tt></b></dt>
- <dd>Convert an integer constant to a pointer constant. TYPE must be a pointer
- type. CST must be of integer type. The CST value is zero extended,
- truncated, or unchanged to make it fit in a pointer size. This one is
- <i>really</i> dangerous!</dd>
-
- <dt><b><tt>bitcast (CST to TYPE)</tt></b></dt>
- <dd>Convert a constant, CST, to another TYPE. The constraints of the operands
- are the same as those for the <a href="#i_bitcast">bitcast
- instruction</a>.</dd>
-
- <dt><b><tt>getelementptr (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
- <dt><b><tt>getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
- <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
- constants. As with the <a href="#i_getelementptr">getelementptr</a>
- instruction, the index list may have zero or more indexes, which are
- required to make sense for the type of "CSTPTR".</dd>
-
- <dt><b><tt>select (COND, VAL1, VAL2)</tt></b></dt>
- <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd>
-
- <dt><b><tt>icmp COND (VAL1, VAL2)</tt></b></dt>
- <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
-
- <dt><b><tt>fcmp COND (VAL1, VAL2)</tt></b></dt>
- <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
-
- <dt><b><tt>extractelement (VAL, IDX)</tt></b></dt>
- <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on
- constants.</dd>
-
- <dt><b><tt>insertelement (VAL, ELT, IDX)</tt></b></dt>
- <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on
- constants.</dd>
-
- <dt><b><tt>shufflevector (VEC1, VEC2, IDXMASK)</tt></b></dt>
- <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on
- constants.</dd>
-
- <dt><b><tt>extractvalue (VAL, IDX0, IDX1, ...)</tt></b></dt>
- <dd>Perform the <a href="#i_extractvalue">extractvalue operation</a> on
- constants. The index list is interpreted in a similar manner as indices in
- a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
- index value must be specified.</dd>
-
- <dt><b><tt>insertvalue (VAL, ELT, IDX0, IDX1, ...)</tt></b></dt>
- <dd>Perform the <a href="#i_insertvalue">insertvalue operation</a> on
- constants. The index list is interpreted in a similar manner as indices in
- a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
- index value must be specified.</dd>
-
- <dt><b><tt>OPCODE (LHS, RHS)</tt></b></dt>
- <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
- be any of the <a href="#binaryops">binary</a>
- or <a href="#bitwiseops">bitwise binary</a> operations. The constraints
- on operands are the same as those for the corresponding instruction
- (e.g. no bitwise operations on floating point values are allowed).</dd>
-</dl>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="othervalues">Other Values</a></h2>
-<!-- *********************************************************************** -->
-<div>
-<!-- ======================================================================= -->
-<h3>
-<a name="inlineasm">Inline Assembler Expressions</a>
-</h3>
-
-<div>
-
-<p>LLVM supports inline assembler expressions (as opposed
- to <a href="#moduleasm">Module-Level Inline Assembly</a>) through the use of
- a special value. This value represents the inline assembler as a string
- (containing the instructions to emit), a list of operand constraints (stored
- as a string), a flag that indicates whether or not the inline asm
- expression has side effects, and a flag indicating whether the function
- containing the asm needs to align its stack conservatively. An example
- inline assembler expression is:</p>
-
-<pre class="doc_code">
-i32 (i32) asm "bswap $0", "=r,r"
-</pre>
-
-<p>Inline assembler expressions may <b>only</b> be used as the callee operand of
- a <a href="#i_call"><tt>call</tt></a> or an
- <a href="#i_invoke"><tt>invoke</tt></a> instruction.
- Thus, typically we have:</p>
-
-<pre class="doc_code">
-%X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
-</pre>
-
-<p>Inline asms with side effects not visible in the constraint list must be
- marked as having side effects. This is done through the use of the
- '<tt>sideeffect</tt>' keyword, like so:</p>
-
-<pre class="doc_code">
-call void asm sideeffect "eieio", ""()
-</pre>
-
-<p>In some cases inline asms will contain code that will not work unless the
- stack is aligned in some way, such as calls or SSE instructions on x86,
- yet will not contain code that does that alignment within the asm.
- The compiler should make conservative assumptions about what the asm might
- contain and should generate its usual stack alignment code in the prologue
- if the '<tt>alignstack</tt>' keyword is present:</p>
-
-<pre class="doc_code">
-call void asm alignstack "eieio", ""()
-</pre>
-
-<p>Inline asms also support using non-standard assembly dialects. The assumed
- dialect is ATT. When the '<tt>inteldialect</tt>' keyword is present, the
- inline asm is using the Intel dialect. Currently, ATT and Intel are the
- only supported dialects. An example is:</p>
-
-<pre class="doc_code">
-call void asm inteldialect "eieio", ""()
-</pre>
-
-<p>If multiple keywords appear the '<tt>sideeffect</tt>' keyword must come
- first, the '<tt>alignstack</tt>' keyword second and the
- '<tt>inteldialect</tt>' keyword last.</p>
-
-<!--
-<p>TODO: The format of the asm and constraints string still need to be
- documented here. Constraints on what can be done (e.g. duplication, moving,
- etc need to be documented). This is probably best done by reference to
- another document that covers inline asm from a holistic perspective.</p>
- -->
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="inlineasm_md">Inline Asm Metadata</a>
-</h4>
-
-<div>
-
-<p>The call instructions that wrap inline asm nodes may have a
- "<tt>!srcloc</tt>" MDNode attached to it that contains a list of constant
- integers. If present, the code generator will use the integer as the
- location cookie value when report errors through the <tt>LLVMContext</tt>
- error reporting mechanisms. This allows a front-end to correlate backend
- errors that occur with inline asm back to the source code that produced it.
- For example:</p>
-
-<pre class="doc_code">
-call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
-...
-!42 = !{ i32 1234567 }
-</pre>
-
-<p>It is up to the front-end to make sense of the magic numbers it places in the
- IR. If the MDNode contains multiple constants, the code generator will use
- the one that corresponds to the line of the asm that the error occurs on.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="metadata">Metadata Nodes and Metadata Strings</a>
-</h3>
-
-<div>
-
-<p>LLVM IR allows metadata to be attached to instructions in the program that
- can convey extra information about the code to the optimizers and code
- generator. One example application of metadata is source-level debug
- information. There are two metadata primitives: strings and nodes. All
- metadata has the <tt>metadata</tt> type and is identified in syntax by a
- preceding exclamation point ('<tt>!</tt>').</p>
-
-<p>A metadata string is a string surrounded by double quotes. It can contain
- any character by escaping non-printable characters with "<tt>\xx</tt>" where
- "<tt>xx</tt>" is the two digit hex code. For example:
- "<tt>!"test\00"</tt>".</p>
-
-<p>Metadata nodes are represented with notation similar to structure constants
- (a comma separated list of elements, surrounded by braces and preceded by an
- exclamation point). Metadata nodes can have any values as their operand. For
- example:</p>
-
-<div class="doc_code">
-<pre>
-!{ metadata !"test\00", i32 10}
-</pre>
-</div>
-
-<p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of
- metadata nodes, which can be looked up in the module symbol table. For
- example:</p>
-
-<div class="doc_code">
-<pre>
-!foo = metadata !{!4, !3}
-</pre>
-</div>
-
-<p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt>
- function is using two metadata arguments:</p>
-
-<div class="doc_code">
-<pre>
-call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
-</pre>
-</div>
-
-<p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is
- attached to the <tt>add</tt> instruction using the <tt>!dbg</tt>
- identifier:</p>
-
-<div class="doc_code">
-<pre>
-%indvar.next = add i64 %indvar, 1, !dbg !21
-</pre>
-</div>
-
-<p>More information about specific metadata nodes recognized by the optimizers
- and code generator is found below.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="tbaa">'<tt>tbaa</tt>' Metadata</a>
-</h4>
-
-<div>
-
-<p>In LLVM IR, memory does not have types, so LLVM's own type system is not
- suitable for doing TBAA. Instead, metadata is added to the IR to describe
- a type system of a higher level language. This can be used to implement
- typical C/C++ TBAA, but it can also be used to implement custom alias
- analysis behavior for other languages.</p>
-
-<p>The current metadata format is very simple. TBAA metadata nodes have up to
- three fields, e.g.:</p>
-
-<div class="doc_code">
-<pre>
-!0 = metadata !{ metadata !"an example type tree" }
-!1 = metadata !{ metadata !"int", metadata !0 }
-!2 = metadata !{ metadata !"float", metadata !0 }
-!3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
-</pre>
-</div>
-
-<p>The first field is an identity field. It can be any value, usually
- a metadata string, which uniquely identifies the type. The most important
- name in the tree is the name of the root node. Two trees with
- different root node names are entirely disjoint, even if they
- have leaves with common names.</p>
-
-<p>The second field identifies the type's parent node in the tree, or
- is null or omitted for a root node. A type is considered to alias
- all of its descendants and all of its ancestors in the tree. Also,
- a type is considered to alias all types in other trees, so that
- bitcode produced from multiple front-ends is handled conservatively.</p>
-
-<p>If the third field is present, it's an integer which if equal to 1
- indicates that the type is "constant" (meaning
- <tt>pointsToConstantMemory</tt> should return true; see
- <a href="AliasAnalysis.html#OtherItfs">other useful
- <tt>AliasAnalysis</tt> methods</a>).</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="tbaa.struct">'<tt>tbaa.struct</tt>' Metadata</a>
-</h4>
-
-<div>
-
-<p>The <a href="#int_memcpy"><tt>llvm.memcpy</tt></a> is often used to implement
-aggregate assignment operations in C and similar languages, however it is
-defined to copy a contiguous region of memory, which is more than strictly
-necessary for aggregate types which contain holes due to padding. Also, it
-doesn't contain any TBAA information about the fields of the aggregate.</p>
-
-<p><tt>!tbaa.struct</tt> metadata can describe which memory subregions in a memcpy
-are padding and what the TBAA tags of the struct are.</p>
-
-<p>The current metadata format is very simple. <tt>!tbaa.struct</tt> metadata nodes
- are a list of operands which are in conceptual groups of three. For each
- group of three, the first operand gives the byte offset of a field in bytes,
- the second gives its size in bytes, and the third gives its
- tbaa tag. e.g.:</p>
-
-<div class="doc_code">
-<pre>
-!4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }
-</pre>
-</div>
-
-<p>This describes a struct with two fields. The first is at offset 0 bytes
- with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
- and has size 4 bytes and has tbaa tag !2.</p>
-
-<p>Note that the fields need not be contiguous. In this example, there is a
- 4 byte gap between the two fields. This gap represents padding which
- does not carry useful data and need not be preserved.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="fpmath">'<tt>fpmath</tt>' Metadata</a>
-</h4>
-
-<div>
-
-<p><tt>fpmath</tt> metadata may be attached to any instruction of floating point
- type. It can be used to express the maximum acceptable error in the result of
- that instruction, in ULPs, thus potentially allowing the compiler to use a
- more efficient but less accurate method of computing it. ULP is defined as
- follows:</p>
-
-<blockquote>
-
-<p>If <tt>x</tt> is a real number that lies between two finite consecutive
- floating-point numbers <tt>a</tt> and <tt>b</tt>, without being equal to one
- of them, then <tt>ulp(x) = |b - a|</tt>, otherwise <tt>ulp(x)</tt> is the
- distance between the two non-equal finite floating-point numbers nearest
- <tt>x</tt>. Moreover, <tt>ulp(NaN)</tt> is <tt>NaN</tt>.</p>
-
-</blockquote>
-
-<p>The metadata node shall consist of a single positive floating point number
- representing the maximum relative error, for example:</p>
-
-<div class="doc_code">
-<pre>
-!0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
-</pre>
-</div>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="range">'<tt>range</tt>' Metadata</a>
-</h4>
-
-<div>
-<p><tt>range</tt> metadata may be attached only to loads of integer types. It
- expresses the possible ranges the loaded value is in. The ranges are
- represented with a flattened list of integers. The loaded value is known to
- be in the union of the ranges defined by each consecutive pair. Each pair
- has the following properties:</p>
-<ul>
- <li>The type must match the type loaded by the instruction.</li>
- <li>The pair <tt>a,b</tt> represents the range <tt>[a,b)</tt>.</li>
- <li>Both <tt>a</tt> and <tt>b</tt> are constants.</li>
- <li>The range is allowed to wrap.</li>
- <li>The range should not represent the full or empty set. That is,
- <tt>a!=b</tt>. </li>
-</ul>
-<p> In addition, the pairs must be in signed order of the lower bound and
- they must be non-contiguous.</p>
-
-<p>Examples:</p>
-<div class="doc_code">
-<pre>
- %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
- %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
- %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
- %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5
-...
-!0 = metadata !{ i8 0, i8 2 }
-!1 = metadata !{ i8 255, i8 2 }
-!2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
-!3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
-</pre>
-</div>
-</div>
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2>
- <a name="module_flags">Module Flags Metadata</a>
-</h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>Information about the module as a whole is difficult to convey to LLVM's
- subsystems. The LLVM IR isn't sufficient to transmit this
- information. The <tt>llvm.module.flags</tt> named metadata exists in order to
- facilitate this. These flags are in the form of key / value pairs —
- much like a dictionary — making it easy for any subsystem who cares
- about a flag to look it up.</p>
-
-<p>The <tt>llvm.module.flags</tt> metadata contains a list of metadata
- triplets. Each triplet has the following form:</p>
-
-<ul>
- <li>The first element is a <i>behavior</i> flag, which specifies the behavior
- when two (or more) modules are merged together, and it encounters two (or
- more) metadata with the same ID. The supported behaviors are described
- below.</li>
-
- <li>The second element is a metadata string that is a unique ID for the
- metadata. How each ID is interpreted is documented below.</li>
-
- <li>The third element is the value of the flag.</li>
-</ul>
-
-<p>When two (or more) modules are merged together, the resulting
- <tt>llvm.module.flags</tt> metadata is the union of the
- modules' <tt>llvm.module.flags</tt> metadata. The only exception being a flag
- with the <i>Override</i> behavior, which may override another flag's value
- (see below).</p>
-
-<p>The following behaviors are supported:</p>
-
-<table border="1" cellspacing="0" cellpadding="4">
- <tbody>
- <tr>
- <th>Value</th>
- <th>Behavior</th>
- </tr>
- <tr>
- <td>1</td>
- <td align="left">
- <dl>
- <dt><b>Error</b></dt>
- <dd>Emits an error if two values disagree. It is an error to have an ID
- with both an Error and a Warning behavior.</dd>
- </dl>
- </td>
- </tr>
- <tr>
- <td>2</td>
- <td align="left">
- <dl>
- <dt><b>Warning</b></dt>
- <dd>Emits a warning if two values disagree.</dd>
- </dl>
- </td>
- </tr>
- <tr>
- <td>3</td>
- <td align="left">
- <dl>
- <dt><b>Require</b></dt>
- <dd>Emits an error when the specified value is not present or doesn't
- have the specified value. It is an error for two (or more)
- <tt>llvm.module.flags</tt> with the same ID to have the Require
- behavior but different values. There may be multiple Require flags
- per ID.</dd>
- </dl>
- </td>
- </tr>
- <tr>
- <td>4</td>
- <td align="left">
- <dl>
- <dt><b>Override</b></dt>
- <dd>Uses the specified value if the two values disagree. It is an
- error for two (or more) <tt>llvm.module.flags</tt> with the same
- ID to have the Override behavior but different values.</dd>
- </dl>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p>An example of module flags:</p>
-
-<pre class="doc_code">
-!0 = metadata !{ i32 1, metadata !"foo", i32 1 }
-!1 = metadata !{ i32 4, metadata !"bar", i32 37 }
-!2 = metadata !{ i32 2, metadata !"qux", i32 42 }
-!3 = metadata !{ i32 3, metadata !"qux",
- metadata !{
- metadata !"foo", i32 1
- }
-}
-!llvm.module.flags = !{ !0, !1, !2, !3 }
-</pre>
-
-<ul>
- <li><p>Metadata <tt>!0</tt> has the ID <tt>!"foo"</tt> and the value '1'. The
- behavior if two or more <tt>!"foo"</tt> flags are seen is to emit an
- error if their values are not equal.</p></li>
-
- <li><p>Metadata <tt>!1</tt> has the ID <tt>!"bar"</tt> and the value '37'. The
- behavior if two or more <tt>!"bar"</tt> flags are seen is to use the
- value '37' if their values are not equal.</p></li>
-
- <li><p>Metadata <tt>!2</tt> has the ID <tt>!"qux"</tt> and the value '42'. The
- behavior if two or more <tt>!"qux"</tt> flags are seen is to emit a
- warning if their values are not equal.</p></li>
-
- <li><p>Metadata <tt>!3</tt> has the ID <tt>!"qux"</tt> and the value:</p>
-
-<pre class="doc_code">
-metadata !{ metadata !"foo", i32 1 }
-</pre>
-
- <p>The behavior is to emit an error if the <tt>llvm.module.flags</tt> does
- not contain a flag with the ID <tt>!"foo"</tt> that has the value
- '1'. If two or more <tt>!"qux"</tt> flags exist, then they must have
- the same value or an error will be issued.</p></li>
-</ul>
-
-
-<!-- ======================================================================= -->
-<h3>
-<a name="objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a>
-</h3>
-
-<div>
-
-<p>On the Mach-O platform, Objective-C stores metadata about garbage collection
- in a special section called "image info". The metadata consists of a version
- number and a bitmask specifying what types of garbage collection are
- supported (if any) by the file. If two or more modules are linked together
- their garbage collection metadata needs to be merged rather than appended
- together.</p>
-
-<p>The Objective-C garbage collection module flags metadata consists of the
- following key-value pairs:</p>
-
-<table border="1" cellspacing="0" cellpadding="4">
- <col width="30%">
- <tbody>
- <tr>
- <th>Key</th>
- <th>Value</th>
- </tr>
- <tr>
- <td><tt>Objective-C Version</tt></td>
- <td align="left"><b>[Required]</b> — The Objective-C ABI
- version. Valid values are 1 and 2.</td>
- </tr>
- <tr>
- <td><tt>Objective-C Image Info Version</tt></td>
- <td align="left"><b>[Required]</b> — The version of the image info
- section. Currently always 0.</td>
- </tr>
- <tr>
- <td><tt>Objective-C Image Info Section</tt></td>
- <td align="left"><b>[Required]</b> — The section to place the
- metadata. Valid values are <tt>"__OBJC, __image_info, regular"</tt> for
- Objective-C ABI version 1, and <tt>"__DATA,__objc_imageinfo, regular,
- no_dead_strip"</tt> for Objective-C ABI version 2.</td>
- </tr>
- <tr>
- <td><tt>Objective-C Garbage Collection</tt></td>
- <td align="left"><b>[Required]</b> — Specifies whether garbage
- collection is supported or not. Valid values are 0, for no garbage
- collection, and 2, for garbage collection supported.</td>
- </tr>
- <tr>
- <td><tt>Objective-C GC Only</tt></td>
- <td align="left"><b>[Optional]</b> — Specifies that only garbage
- collection is supported. If present, its value must be 6. This flag
- requires that the <tt>Objective-C Garbage Collection</tt> flag have the
- value 2.</td>
- </tr>
- </tbody>
-</table>
-
-<p>Some important flag interactions:</p>
-
-<ul>
- <li>If a module with <tt>Objective-C Garbage Collection</tt> set to 0 is
- merged with a module with <tt>Objective-C Garbage Collection</tt> set to
- 2, then the resulting module has the <tt>Objective-C Garbage
- Collection</tt> flag set to 0.</li>
-
- <li>A module with <tt>Objective-C Garbage Collection</tt> set to 0 cannot be
- merged with a module with <tt>Objective-C GC Only</tt> set to 6.</li>
-</ul>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2>
- <a name="intrinsic_globals">Intrinsic Global Variables</a>
-</h2>
-<!-- *********************************************************************** -->
-<div>
-<p>LLVM has a number of "magic" global variables that contain data that affect
-code generation or other IR semantics. These are documented here. All globals
-of this sort should have a section specified as "<tt>llvm.metadata</tt>". This
-section and all globals that start with "<tt>llvm.</tt>" are reserved for use
-by LLVM.</p>
-
-<!-- ======================================================================= -->
-<h3>
-<a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a>
-</h3>
-
-<div>
-
-<p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a
-href="#linkage_appending">appending linkage</a>. This array contains a list of
-pointers to global variables and functions which may optionally have a pointer
-cast formed of bitcast or getelementptr. For example, a legal use of it is:</p>
-
-<div class="doc_code">
-<pre>
-@X = global i8 4
-@Y = global i32 123
-
-@llvm.used = appending global [2 x i8*] [
- i8* @X,
- i8* bitcast (i32* @Y to i8*)
-], section "llvm.metadata"
-</pre>
-</div>
-
-<p>If a global variable appears in the <tt>@llvm.used</tt> list, then the
- compiler, assembler, and linker are required to treat the symbol as if there
- is a reference to the global that it cannot see. For example, if a variable
- has internal linkage and no references other than that from
- the <tt>@llvm.used</tt> list, it cannot be deleted. This is commonly used to
- represent references from inline asms and other things the compiler cannot
- "see", and corresponds to "<tt>attribute((used))</tt>" in GNU C.</p>
-
-<p>On some targets, the code generator must emit a directive to the assembler or
- object file to prevent the assembler and linker from molesting the
- symbol.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="intg_compiler_used">
- The '<tt>llvm.compiler.used</tt>' Global Variable
- </a>
-</h3>
-
-<div>
-
-<p>The <tt>@llvm.compiler.used</tt> directive is the same as the
- <tt>@llvm.used</tt> directive, except that it only prevents the compiler from
- touching the symbol. On targets that support it, this allows an intelligent
- linker to optimize references to the symbol without being impeded as it would
- be by <tt>@llvm.used</tt>.</p>
-
-<p>This is a rare construct that should only be used in rare circumstances, and
- should not be exposed to source languages.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-<a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a>
-</h3>
-
-<div>
-
-<div class="doc_code">
-<pre>
-%0 = type { i32, void ()* }
-@llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
-</pre>
-</div>
-
-<p>The <tt>@llvm.global_ctors</tt> array contains a list of constructor
- functions and associated priorities. The functions referenced by this array
- will be called in ascending order of priority (i.e. lowest first) when the
- module is loaded. The order of functions with the same priority is not
- defined.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
-<a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a>
-</h3>
-
-<div>
-
-<div class="doc_code">
-<pre>
-%0 = type { i32, void ()* }
-@llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
-</pre>
-</div>
-
-<p>The <tt>@llvm.global_dtors</tt> array contains a list of destructor functions
- and associated priorities. The functions referenced by this array will be
- called in descending order of priority (i.e. highest first) when the module
- is loaded. The order of functions with the same priority is not defined.</p>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="instref">Instruction Reference</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>The LLVM instruction set consists of several different classifications of
- instructions: <a href="#terminators">terminator
- instructions</a>, <a href="#binaryops">binary instructions</a>,
- <a href="#bitwiseops">bitwise binary instructions</a>,
- <a href="#memoryops">memory instructions</a>, and
- <a href="#otherops">other instructions</a>.</p>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="terminators">Terminator Instructions</a>
-</h3>
-
-<div>
-
-<p>As mentioned <a href="#functionstructure">previously</a>, every basic block
- in a program ends with a "Terminator" instruction, which indicates which
- block should be executed after the current block is finished. These
- terminator instructions typically yield a '<tt>void</tt>' value: they produce
- control flow, not values (the one exception being the
- '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
-
-<p>The terminator instructions are:
- '<a href="#i_ret"><tt>ret</tt></a>',
- '<a href="#i_br"><tt>br</tt></a>',
- '<a href="#i_switch"><tt>switch</tt></a>',
- '<a href="#i_indirectbr"><tt>indirectbr</tt></a>',
- '<a href="#i_invoke"><tt>invoke</tt></a>',
- '<a href="#i_resume"><tt>resume</tt></a>', and
- '<a href="#i_unreachable"><tt>unreachable</tt></a>'.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_ret">'<tt>ret</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- ret <type> <value> <i>; Return a value from a non-void function</i>
- ret void <i>; Return from void function</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally
- a value) from a function back to the caller.</p>
-
-<p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a
- value and then causes control flow, and one that just causes control flow to
- occur.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the
- return value. The type of the return value must be a
- '<a href="#t_firstclass">first class</a>' type.</p>
-
-<p>A function is not <a href="#wellformed">well formed</a> if it it has a
- non-void return type and contains a '<tt>ret</tt>' instruction with no return
- value or a return value with a type that does not match its type, or if it
- has a void return type and contains a '<tt>ret</tt>' instruction with a
- return value.</p>
-
-<h5>Semantics:</h5>
-<p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to
- the calling function's context. If the caller is a
- "<a href="#i_call"><tt>call</tt></a>" instruction, execution continues at the
- instruction after the call. If the caller was an
- "<a href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at
- the beginning of the "normal" destination block. If the instruction returns
- a value, that value shall set the call or invoke instruction's return
- value.</p>
-
-<h5>Example:</h5>
-<pre>
- ret i32 5 <i>; Return an integer value of 5</i>
- ret void <i>; Return from a void function</i>
- ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct of values 4 and 2</i>
-</pre>
-
-</div>
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_br">'<tt>br</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- br i1 <cond>, label <iftrue>, label <iffalse>
- br label <dest> <i>; Unconditional branch</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
- different basic block in the current function. There are two forms of this
- instruction, corresponding to a conditional branch and an unconditional
- branch.</p>
-
-<h5>Arguments:</h5>
-<p>The conditional branch form of the '<tt>br</tt>' instruction takes a single
- '<tt>i1</tt>' value and two '<tt>label</tt>' values. The unconditional form
- of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
- target.</p>
-
-<h5>Semantics:</h5>
-<p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>'
- argument is evaluated. If the value is <tt>true</tt>, control flows to the
- '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
- control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
-
-<h5>Example:</h5>
-<pre>
-Test:
- %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b
- br i1 %cond, label %IfEqual, label %IfUnequal
-IfEqual:
- <a href="#i_ret">ret</a> i32 1
-IfUnequal:
- <a href="#i_ret">ret</a> i32 0
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_switch">'<tt>switch</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
- several different places. It is a generalization of the '<tt>br</tt>'
- instruction, allowing a branch to occur to one of many possible
- destinations.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>switch</tt>' instruction uses three parameters: an integer
- comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination,
- and an array of pairs of comparison value constants and '<tt>label</tt>'s.
- The table is not allowed to contain duplicate constant entries.</p>
-
-<h5>Semantics:</h5>
-<p>The <tt>switch</tt> instruction specifies a table of values and
- destinations. When the '<tt>switch</tt>' instruction is executed, this table
- is searched for the given value. If the value is found, control flow is
- transferred to the corresponding destination; otherwise, control flow is
- transferred to the default destination.</p>
-
-<h5>Implementation:</h5>
-<p>Depending on properties of the target machine and the particular
- <tt>switch</tt> instruction, this instruction may be code generated in
- different ways. For example, it could be generated as a series of chained
- conditional branches or with a lookup table.</p>
-
-<h5>Example:</h5>
-<pre>
- <i>; Emulate a conditional br instruction</i>
- %Val = <a href="#i_zext">zext</a> i1 %value to i32
- switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
-
- <i>; Emulate an unconditional br instruction</i>
- switch i32 0, label %dest [ ]
-
- <i>; Implement a jump table:</i>
- switch i32 %val, label %otherwise [ i32 0, label %onzero
- i32 1, label %onone
- i32 2, label %ontwo ]
-</pre>
-
-</div>
-
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
-</pre>
-
-<h5>Overview:</h5>
-
-<p>The '<tt>indirectbr</tt>' instruction implements an indirect branch to a label
- within the current function, whose address is specified by
- "<tt>address</tt>". Address must be derived from a <a
- href="#blockaddress">blockaddress</a> constant.</p>
-
-<h5>Arguments:</h5>
-
-<p>The '<tt>address</tt>' argument is the address of the label to jump to. The
- rest of the arguments indicate the full set of possible destinations that the
- address may point to. Blocks are allowed to occur multiple times in the
- destination list, though this isn't particularly useful.</p>
-
-<p>This destination list is required so that dataflow analysis has an accurate
- understanding of the CFG.</p>
-
-<h5>Semantics:</h5>
-
-<p>Control transfers to the block specified in the address argument. All
- possible destination blocks must be listed in the label list, otherwise this
- instruction has undefined behavior. This implies that jumps to labels
- defined in other functions have undefined behavior as well.</p>
-
-<h5>Implementation:</h5>
-
-<p>This is typically implemented with a jump through a register.</p>
-
-<h5>Example:</h5>
-<pre>
- indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
-</pre>
-
-</div>
-
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = invoke [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] <ptr to function ty> <function ptr val>(<function args>) [<a href="#fnattrs">fn attrs</a>]
- to label <normal label> unwind label <exception label>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
- function, with the possibility of control flow transfer to either the
- '<tt>normal</tt>' label or the '<tt>exception</tt>' label. If the callee
- function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction,
- control flow will return to the "normal" label. If the callee (or any
- indirect callees) returns via the "<a href="#i_resume"><tt>resume</tt></a>"
- instruction or other exception handling mechanism, control is interrupted and
- continued at the dynamically nearest "exception" label.</p>
-
-<p>The '<tt>exception</tt>' label is a
- <i><a href="ExceptionHandling.html#overview">landing pad</a></i> for the
- exception. As such, '<tt>exception</tt>' label is required to have the
- "<a href="#i_landingpad"><tt>landingpad</tt></a>" instruction, which contains
- the information about the behavior of the program after unwinding
- happens, as its first non-PHI instruction. The restrictions on the
- "<tt>landingpad</tt>" instruction's tightly couples it to the
- "<tt>invoke</tt>" instruction, so that the important information contained
- within the "<tt>landingpad</tt>" instruction can't be lost through normal
- code motion.</p>
-
-<h5>Arguments:</h5>
-<p>This instruction requires several arguments:</p>
-
-<ol>
- <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
- convention</a> the call should use. If none is specified, the call
- defaults to using C calling conventions.</li>
-
- <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
- return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
- '<tt>inreg</tt>' attributes are valid here.</li>
-
- <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
- function value being invoked. In most cases, this is a direct function
- invocation, but indirect <tt>invoke</tt>s are just as possible, branching
- off an arbitrary pointer to function value.</li>
-
- <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
- function to be invoked. </li>
-
- <li>'<tt>function args</tt>': argument list whose types match the function
- signature argument types and parameter attributes. All arguments must be
- of <a href="#t_firstclass">first class</a> type. If the function
- signature indicates the function accepts a variable number of arguments,
- the extra arguments can be specified.</li>
-
- <li>'<tt>normal label</tt>': the label reached when the called function
- executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
-
- <li>'<tt>exception label</tt>': the label reached when a callee returns via
- the <a href="#i_resume"><tt>resume</tt></a> instruction or other exception
- handling mechanism.</li>
-
- <li>The optional <a href="#fnattrs">function attributes</a> list. Only
- '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
- '<tt>readnone</tt>' attributes are valid here.</li>
-</ol>
-
-<h5>Semantics:</h5>
-<p>This instruction is designed to operate as a standard
- '<tt><a href="#i_call">call</a></tt>' instruction in most regards. The
- primary difference is that it establishes an association with a label, which
- is used by the runtime library to unwind the stack.</p>
-
-<p>This instruction is used in languages with destructors to ensure that proper
- cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
- exception. Additionally, this is important for implementation of
- '<tt>catch</tt>' clauses in high-level languages that support them.</p>
-
-<p>For the purposes of the SSA form, the definition of the value returned by the
- '<tt>invoke</tt>' instruction is deemed to occur on the edge from the current
- block to the "normal" label. If the callee unwinds then no return value is
- available.</p>
-
-<h5>Example:</h5>
-<pre>
- %retval = invoke i32 @Test(i32 15) to label %Continue
- unwind label %TestCleanup <i>; {i32}:retval set</i>
- %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue
- unwind label %TestCleanup <i>; {i32}:retval set</i>
-</pre>
-
-</div>
-
- <!-- _______________________________________________________________________ -->
-
-<h4>
- <a name="i_resume">'<tt>resume</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- resume <type> <value>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>resume</tt>' instruction is a terminator instruction that has no
- successors.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>resume</tt>' instruction requires one argument, which must have the
- same type as the result of any '<tt>landingpad</tt>' instruction in the same
- function.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>resume</tt>' instruction resumes propagation of an existing
- (in-flight) exception whose unwinding was interrupted with
- a <a href="#i_landingpad"><tt>landingpad</tt></a> instruction.</p>
-
-<h5>Example:</h5>
-<pre>
- resume { i8*, i32 } %exn
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-
-<h4>
- <a name="i_unreachable">'<tt>unreachable</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- unreachable
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>unreachable</tt>' instruction has no defined semantics. This
- instruction is used to inform the optimizer that a particular portion of the
- code is not reachable. This can be used to indicate that the code after a
- no-return function cannot be reached, and other facts.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="binaryops">Binary Operations</a>
-</h3>
-
-<div>
-
-<p>Binary operators are used to do most of the computation in a program. They
- require two operands of the same type, execute an operation on them, and
- produce a single value. The operands might represent multiple data, as is
- the case with the <a href="#t_vector">vector</a> data type. The result value
- has the same type as its operands.</p>
-
-<p>There are several different binary operators:</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_add">'<tt>add</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = add nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = add nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = add nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>add</tt>' instruction must
- be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
- integer values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The value produced is the integer sum of the two operands.</p>
-
-<p>If the sum has unsigned overflow, the result returned is the mathematical
- result modulo 2<sup>n</sup>, where n is the bit width of the result.</p>
-
-<p>Because LLVM integers use a two's complement representation, this instruction
- is appropriate for both signed and unsigned integers.</p>
-
-<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
- and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
- <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
- is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
- respectively, occurs.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = add i32 4, %var <i>; yields {i32}:result = 4 + %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fadd">'<tt>fadd</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fadd [fast-math flags]* <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>fadd</tt>' instruction must be
- <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
- floating point values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
- <p>The value produced is the floating point sum of the two operands. This
- instruction can also take any number of <a href="#fastmath">fast-math
- flags</a>, which are optimization hints to enable otherwise unsafe floating
- point optimizations:</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = fadd float 4.0, %var <i>; yields {float}:result = 4.0 + %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_sub">'<tt>sub</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = sub nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = sub nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = sub nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>sub</tt>' instruction returns the difference of its two
- operands.</p>
-
-<p>Note that the '<tt>sub</tt>' instruction is used to represent the
- '<tt>neg</tt>' instruction present in most other intermediate
- representations.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>sub</tt>' instruction must
- be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
- integer values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The value produced is the integer difference of the two operands.</p>
-
-<p>If the difference has unsigned overflow, the result returned is the
- mathematical result modulo 2<sup>n</sup>, where n is the bit width of the
- result.</p>
-
-<p>Because LLVM integers use a two's complement representation, this instruction
- is appropriate for both signed and unsigned integers.</p>
-
-<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
- and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
- <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
- is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
- respectively, occurs.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = sub i32 4, %var <i>; yields {i32}:result = 4 - %var</i>
- <result> = sub i32 0, %val <i>; yields {i32}:result = -%var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fsub">'<tt>fsub</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fsub [fast-math flags]* <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fsub</tt>' instruction returns the difference of its two
- operands.</p>
-
-<p>Note that the '<tt>fsub</tt>' instruction is used to represent the
- '<tt>fneg</tt>' instruction present in most other intermediate
- representations.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>fsub</tt>' instruction must be
- <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
- floating point values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
- <p>The value produced is the floating point difference of the two operands.
- This instruction can also take any number of <a href="#fastmath">fast-math
- flags</a>, which are optimization hints to enable otherwise unsafe floating
- point optimizations:</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = fsub float 4.0, %var <i>; yields {float}:result = 4.0 - %var</i>
- <result> = fsub float -0.0, %val <i>; yields {float}:result = -%var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_mul">'<tt>mul</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = mul nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = mul nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = mul nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>mul</tt>' instruction must
- be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
- integer values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The value produced is the integer product of the two operands.</p>
-
-<p>If the result of the multiplication has unsigned overflow, the result
- returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit
- width of the result.</p>
-
-<p>Because LLVM integers use a two's complement representation, and the result
- is the same width as the operands, this instruction returns the correct
- result for both signed and unsigned integers. If a full product
- (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should
- be sign-extended or zero-extended as appropriate to the width of the full
- product.</p>
-
-<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
- and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
- <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
- is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
- respectively, occurs.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fmul">'<tt>fmul</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fmul [fast-math flags]* <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>fmul</tt>' instruction must be
- <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
- floating point values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
- <p>The value produced is the floating point product of the two operands. This
- instruction can also take any number of <a href="#fastmath">fast-math
- flags</a>, which are optimization hints to enable otherwise unsafe floating
- point optimizations:</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = fmul float 4.0, %var <i>; yields {float}:result = 4.0 * %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_udiv">'<tt>udiv</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = udiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>udiv</tt>' instruction must be
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The value produced is the unsigned integer quotient of the two operands.</p>
-
-<p>Note that unsigned integer division and signed integer division are distinct
- operations; for signed integer division, use '<tt>sdiv</tt>'.</p>
-
-<p>Division by zero leads to undefined behavior.</p>
-
-<p>If the <tt>exact</tt> keyword is present, the result value of the
- <tt>udiv</tt> is a <a href="#poisonvalues">poison value</a> if %op1 is not a
- multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p>
-
-
-<h5>Example:</h5>
-<pre>
- <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_sdiv">'<tt>sdiv</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = sdiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>sdiv</tt>' instruction must be
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The value produced is the signed integer quotient of the two operands rounded
- towards zero.</p>
-
-<p>Note that signed integer division and unsigned integer division are distinct
- operations; for unsigned integer division, use '<tt>udiv</tt>'.</p>
-
-<p>Division by zero leads to undefined behavior. Overflow also leads to
- undefined behavior; this is a rare case, but can occur, for example, by doing
- a 32-bit division of -2147483648 by -1.</p>
-
-<p>If the <tt>exact</tt> keyword is present, the result value of the
- <tt>sdiv</tt> is a <a href="#poisonvalues">poison value</a> if the result would
- be rounded.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fdiv">'<tt>fdiv</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>fdiv</tt>' instruction must be
- <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
- floating point values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
- <p>The value produced is the floating point quotient of the two operands. This
- instruction can also take any number of <a href="#fastmath">fast-math
- flags</a>, which are optimization hints to enable otherwise unsafe floating
- point optimizations:</p>
-</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = fdiv float 4.0, %var <i>; yields {float}:result = 4.0 / %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_urem">'<tt>urem</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = urem <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned
- division of its two arguments.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>urem</tt>' instruction must be
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>This instruction returns the unsigned integer <i>remainder</i> of a division.
- This instruction always performs an unsigned division to get the
- remainder.</p>
-
-<p>Note that unsigned integer remainder and signed integer remainder are
- distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p>
-
-<p>Taking the remainder of a division by zero leads to undefined behavior.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_srem">'<tt>srem</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = srem <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>srem</tt>' instruction returns the remainder from the signed
- division of its two operands. This instruction can also take
- <a href="#t_vector">vector</a> versions of the values in which case the
- elements must be integers.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>srem</tt>' instruction must be
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>This instruction returns the <i>remainder</i> of a division (where the result
- is either zero or has the same sign as the dividend, <tt>op1</tt>), not the
- <i>modulo</i> operator (where the result is either zero or has the same sign
- as the divisor, <tt>op2</tt>) of a value.
- For more information about the difference,
- see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
- Math Forum</a>. For a table of how this is implemented in various languages,
- please see <a href="http://en.wikipedia.org/wiki/Modulo_operation">
- Wikipedia: modulo operation</a>.</p>
-
-<p>Note that signed integer remainder and unsigned integer remainder are
- distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p>
-
-<p>Taking the remainder of a division by zero leads to undefined behavior.
- Overflow also leads to undefined behavior; this is a rare case, but can
- occur, for example, by taking the remainder of a 32-bit division of
- -2147483648 by -1. (The remainder doesn't actually overflow, but this rule
- lets srem be implemented using instructions that return both the result of
- the division and the remainder.)</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_frem">'<tt>frem</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = frem [fast-math flags]* <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>frem</tt>' instruction returns the remainder from the division of
- its two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>frem</tt>' instruction must be
- <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
- floating point values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
- <p>This instruction returns the <i>remainder</i> of a division. The remainder
- has the same sign as the dividend. This instruction can also take any number
- of <a href="#fastmath">fast-math flags</a>, which are optimization hints to
- enable otherwise unsafe floating point optimizations:</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = frem float 4.0, %var <i>; yields {float}:result = 4.0 % %var</i>
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="bitwiseops">Bitwise Binary Operations</a>
-</h3>
-
-<div>
-
-<p>Bitwise binary operators are used to do various forms of bit-twiddling in a
- program. They are generally very efficient instructions and can commonly be
- strength reduced from other instructions. They require two operands of the
- same type, execute an operation on them, and produce a single value. The
- resulting value is the same type as its operands.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_shl">'<tt>shl</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = shl nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = shl nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = shl nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left
- a specified number of bits.</p>
-
-<h5>Arguments:</h5>
-<p>Both arguments to the '<tt>shl</tt>' instruction must be the
- same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
- integer type. '<tt>op2</tt>' is treated as an unsigned value.</p>
-
-<h5>Semantics:</h5>
-<p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod
- 2<sup>n</sup>, where <tt>n</tt> is the width of the result. If <tt>op2</tt>
- is (statically or dynamically) negative or equal to or larger than the number
- of bits in <tt>op1</tt>, the result is undefined. If the arguments are
- vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
- shift amount in <tt>op2</tt>.</p>
-
-<p>If the <tt>nuw</tt> keyword is present, then the shift produces a
- <a href="#poisonvalues">poison value</a> if it shifts out any non-zero bits. If
- the <tt>nsw</tt> keyword is present, then the shift produces a
- <a href="#poisonvalues">poison value</a> if it shifts out any bits that disagree
- with the resultant sign bit. As such, NUW/NSW have the same semantics as
- they would if the shift were expressed as a mul instruction with the same
- nsw/nuw bits in (mul %op1, (shl 1, %op2)).</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i>
- <result> = shl i32 4, 2 <i>; yields {i32}: 16</i>
- <result> = shl i32 1, 10 <i>; yields {i32}: 1024</i>
- <result> = shl i32 1, 32 <i>; undefined</i>
- <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 2, i32 4></i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_lshr">'<tt>lshr</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = lshr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
- operand shifted to the right a specified number of bits with zero fill.</p>
-
-<h5>Arguments:</h5>
-<p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- type. '<tt>op2</tt>' is treated as an unsigned value.</p>
-
-<h5>Semantics:</h5>
-<p>This instruction always performs a logical shift right operation. The most
- significant bits of the result will be filled with zero bits after the shift.
- If <tt>op2</tt> is (statically or dynamically) equal to or larger than the
- number of bits in <tt>op1</tt>, the result is undefined. If the arguments are
- vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
- shift amount in <tt>op2</tt>.</p>
-
-<p>If the <tt>exact</tt> keyword is present, the result value of the
- <tt>lshr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits
- shifted out are non-zero.</p>
-
-
-<h5>Example:</h5>
-<pre>
- <result> = lshr i32 4, 1 <i>; yields {i32}:result = 2</i>
- <result> = lshr i32 4, 2 <i>; yields {i32}:result = 1</i>
- <result> = lshr i8 4, 3 <i>; yields {i8}:result = 0</i>
- <result> = lshr i8 -2, 1 <i>; yields {i8}:result = 0x7FFFFFFF </i>
- <result> = lshr i32 1, 32 <i>; undefined</i>
- <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1></i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_ashr">'<tt>ashr</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = ashr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
- operand shifted to the right a specified number of bits with sign
- extension.</p>
-
-<h5>Arguments:</h5>
-<p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- type. '<tt>op2</tt>' is treated as an unsigned value.</p>
-
-<h5>Semantics:</h5>
-<p>This instruction always performs an arithmetic shift right operation, The
- most significant bits of the result will be filled with the sign bit
- of <tt>op1</tt>. If <tt>op2</tt> is (statically or dynamically) equal to or
- larger than the number of bits in <tt>op1</tt>, the result is undefined. If
- the arguments are vectors, each vector element of <tt>op1</tt> is shifted by
- the corresponding shift amount in <tt>op2</tt>.</p>
-
-<p>If the <tt>exact</tt> keyword is present, the result value of the
- <tt>ashr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits
- shifted out are non-zero.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = ashr i32 4, 1 <i>; yields {i32}:result = 2</i>
- <result> = ashr i32 4, 2 <i>; yields {i32}:result = 1</i>
- <result> = ashr i8 4, 3 <i>; yields {i8}:result = 0</i>
- <result> = ashr i8 -2, 1 <i>; yields {i8}:result = -1</i>
- <result> = ashr i32 1, 32 <i>; undefined</i>
- <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> <i>; yields: result=<2 x i32> < i32 -1, i32 0></i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_and">'<tt>and</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = and <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two
- operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>and</tt>' instruction must be
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The truth table used for the '<tt>and</tt>' instruction is:</p>
-
-<table border="1" cellspacing="0" cellpadding="4">
- <tbody>
- <tr>
- <th>In0</th>
- <th>In1</th>
- <th>Out</th>
- </tr>
- <tr>
- <td>0</td>
- <td>0</td>
- <td>0</td>
- </tr>
- <tr>
- <td>0</td>
- <td>1</td>
- <td>0</td>
- </tr>
- <tr>
- <td>1</td>
- <td>0</td>
- <td>0</td>
- </tr>
- <tr>
- <td>1</td>
- <td>1</td>
- <td>1</td>
- </tr>
- </tbody>
-</table>
-
-<h5>Example:</h5>
-<pre>
- <result> = and i32 4, %var <i>; yields {i32}:result = 4 & %var</i>
- <result> = and i32 15, 40 <i>; yields {i32}:result = 8</i>
- <result> = and i32 4, 8 <i>; yields {i32}:result = 0</i>
-</pre>
-</div>
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_or">'<tt>or</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = or <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its
- two operands.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>or</tt>' instruction must be
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The truth table used for the '<tt>or</tt>' instruction is:</p>
-
-<table border="1" cellspacing="0" cellpadding="4">
- <tbody>
- <tr>
- <th>In0</th>
- <th>In1</th>
- <th>Out</th>
- </tr>
- <tr>
- <td>0</td>
- <td>0</td>
- <td>0</td>
- </tr>
- <tr>
- <td>0</td>
- <td>1</td>
- <td>1</td>
- </tr>
- <tr>
- <td>1</td>
- <td>0</td>
- <td>1</td>
- </tr>
- <tr>
- <td>1</td>
- <td>1</td>
- <td>1</td>
- </tr>
- </tbody>
-</table>
-
-<h5>Example:</h5>
-<pre>
- <result> = or i32 4, %var <i>; yields {i32}:result = 4 | %var</i>
- <result> = or i32 15, 40 <i>; yields {i32}:result = 47</i>
- <result> = or i32 4, 8 <i>; yields {i32}:result = 12</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_xor">'<tt>xor</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = xor <ty> <op1>, <op2> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of
- its two operands. The <tt>xor</tt> is used to implement the "one's
- complement" operation, which is the "~" operator in C.</p>
-
-<h5>Arguments:</h5>
-<p>The two arguments to the '<tt>xor</tt>' instruction must be
- <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
- values. Both arguments must have identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
-
-<table border="1" cellspacing="0" cellpadding="4">
- <tbody>
- <tr>
- <th>In0</th>
- <th>In1</th>
- <th>Out</th>
- </tr>
- <tr>
- <td>0</td>
- <td>0</td>
- <td>0</td>
- </tr>
- <tr>
- <td>0</td>
- <td>1</td>
- <td>1</td>
- </tr>
- <tr>
- <td>1</td>
- <td>0</td>
- <td>1</td>
- </tr>
- <tr>
- <td>1</td>
- <td>1</td>
- <td>0</td>
- </tr>
- </tbody>
-</table>
-
-<h5>Example:</h5>
-<pre>
- <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i>
- <result> = xor i32 15, 40 <i>; yields {i32}:result = 39</i>
- <result> = xor i32 4, 8 <i>; yields {i32}:result = 12</i>
- <result> = xor i32 %V, -1 <i>; yields {i32}:result = ~%V</i>
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="vectorops">Vector Operations</a>
-</h3>
-
-<div>
-
-<p>LLVM supports several instructions to represent vector operations in a
- target-independent manner. These instructions cover the element-access and
- vector-specific operations needed to process vectors effectively. While LLVM
- does directly support these vector operations, many sophisticated algorithms
- will want to use target-specific intrinsics to take full advantage of a
- specific target.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = extractelement <n x <ty>> <val>, i32 <idx> <i>; yields <ty></i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>extractelement</tt>' instruction extracts a single scalar element
- from a vector at a specified index.</p>
-
-
-<h5>Arguments:</h5>
-<p>The first operand of an '<tt>extractelement</tt>' instruction is a value
- of <a href="#t_vector">vector</a> type. The second operand is an index
- indicating the position from which to extract the element. The index may be
- a variable.</p>
-
-<h5>Semantics:</h5>
-<p>The result is a scalar of the same type as the element type of
- <tt>val</tt>. Its value is the value at position <tt>idx</tt> of
- <tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
- results are undefined.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx> <i>; yields <n x <ty>></i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a
- vector at a specified index.</p>
-
-<h5>Arguments:</h5>
-<p>The first operand of an '<tt>insertelement</tt>' instruction is a value
- of <a href="#t_vector">vector</a> type. The second operand is a scalar value
- whose type must equal the element type of the first operand. The third
- operand is an index indicating the position at which to insert the value.
- The index may be a variable.</p>
-
-<h5>Semantics:</h5>
-<p>The result is a vector of the same type as <tt>val</tt>. Its element values
- are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the
- value <tt>elt</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
- results are undefined.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> <i>; yields <m x <ty>></i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
- from two input vectors, returning a vector with the same element type as the
- input and length that is the same as the shuffle mask.</p>
-
-<h5>Arguments:</h5>
-<p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
- with the same type. The third argument is a shuffle mask whose
- element type is always 'i32'. The result of the instruction is a vector
- whose length is the same as the shuffle mask and whose element type is the
- same as the element type of the first two operands.</p>
-
-<p>The shuffle mask operand is required to be a constant vector with either
- constant integer or undef values.</p>
-
-<h5>Semantics:</h5>
-<p>The elements of the two input vectors are numbered from left to right across
- both of the vectors. The shuffle mask operand specifies, for each element of
- the result vector, which element of the two input vectors the result element
- gets. The element selector may be undef (meaning "don't care") and the
- second operand may be undef if performing a shuffle from only one vector.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
- <4 x i32> <i32 0, i32 4, i32 1, i32 5> <i>; yields <4 x i32></i>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
- <4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i> - Identity shuffle.
- <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
- <4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i>
- <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
- <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > <i>; yields <8 x i32></i>
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="aggregateops">Aggregate Operations</a>
-</h3>
-
-<div>
-
-<p>LLVM supports several instructions for working with
- <a href="#t_aggregate">aggregate</a> values.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_extractvalue">'<tt>extractvalue</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>extractvalue</tt>' instruction extracts the value of a member field
- from an <a href="#t_aggregate">aggregate</a> value.</p>
-
-<h5>Arguments:</h5>
-<p>The first operand of an '<tt>extractvalue</tt>' instruction is a value
- of <a href="#t_struct">struct</a> or
- <a href="#t_array">array</a> type. The operands are constant indices to
- specify which value to extract in a similar manner as indices in a
- '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
- <p>The major differences to <tt>getelementptr</tt> indexing are:</p>
- <ul>
- <li>Since the value being indexed is not a pointer, the first index is
- omitted and assumed to be zero.</li>
- <li>At least one index must be specified.</li>
- <li>Not only struct indices but also array indices must be in
- bounds.</li>
- </ul>
-
-<h5>Semantics:</h5>
-<p>The result is the value at the position in the aggregate specified by the
- index operands.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = extractvalue {i32, float} %agg, 0 <i>; yields i32</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_insertvalue">'<tt>insertvalue</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* <i>; yields <aggregate type></i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>insertvalue</tt>' instruction inserts a value into a member field
- in an <a href="#t_aggregate">aggregate</a> value.</p>
-
-<h5>Arguments:</h5>
-<p>The first operand of an '<tt>insertvalue</tt>' instruction is a value
- of <a href="#t_struct">struct</a> or
- <a href="#t_array">array</a> type. The second operand is a first-class
- value to insert. The following operands are constant indices indicating
- the position at which to insert the value in a similar manner as indices in a
- '<tt><a href="#i_extractvalue">extractvalue</a></tt>' instruction. The
- value to insert must have the same type as the value identified by the
- indices.</p>
-
-<h5>Semantics:</h5>
-<p>The result is an aggregate of the same type as <tt>val</tt>. Its value is
- that of <tt>val</tt> except that the value at the position specified by the
- indices is that of <tt>elt</tt>.</p>
-
-<h5>Example:</h5>
-<pre>
- %agg1 = insertvalue {i32, float} undef, i32 1, 0 <i>; yields {i32 1, float undef}</i>
- %agg2 = insertvalue {i32, float} %agg1, float %val, 1 <i>; yields {i32 1, float %val}</i>
- %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0 <i>; yields {i32 1, float %val}</i>
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="memoryops">Memory Access and Addressing Operations</a>
-</h3>
-
-<div>
-
-<p>A key design point of an SSA-based representation is how it represents
- memory. In LLVM, no memory locations are in SSA form, which makes things
- very simple. This section describes how to read, write, and allocate
- memory in LLVM.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = alloca <type>[, <ty> <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the
- currently executing function, to be automatically released when this function
- returns to its caller. The object is always allocated in the generic address
- space (address space zero).</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>alloca</tt>' instruction
- allocates <tt>sizeof(<type>)*NumElements</tt> bytes of memory on the
- runtime stack, returning a pointer of the appropriate type to the program.
- If "NumElements" is specified, it is the number of elements allocated,
- otherwise "NumElements" is defaulted to be one. If a constant alignment is
- specified, the value result of the allocation is guaranteed to be aligned to
- at least that boundary. If not specified, or if zero, the target can choose
- to align the allocation on any convenient boundary compatible with the
- type.</p>
-
-<p>'<tt>type</tt>' may be any sized type.</p>
-
-<h5>Semantics:</h5>
-<p>Memory is allocated; a pointer is returned. The operation is undefined if
- there is insufficient stack space for the allocation. '<tt>alloca</tt>'d
- memory is automatically released when the function returns. The
- '<tt>alloca</tt>' instruction is commonly used to represent automatic
- variables that must have an address available. When the function returns
- (either with the <tt><a href="#i_ret">ret</a></tt>
- or <tt><a href="#i_resume">resume</a></tt> instructions), the memory is
- reclaimed. Allocating zero bytes is legal, but the result is undefined.
- The order in which memory is allocated (ie., which way the stack grows) is
- not specified.</p>
-
-<p>
-
-<h5>Example:</h5>
-<pre>
- %ptr = alloca i32 <i>; yields {i32*}:ptr</i>
- %ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i>
- %ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i>
- %ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_load">'<tt>load</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>]
- <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
- !<index> = !{ i32 1 }
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>load</tt>' instruction is used to read from memory.</p>
-
-<h5>Arguments:</h5>
-<p>The argument to the '<tt>load</tt>' instruction specifies the memory address
- from which to load. The pointer must point to
- a <a href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
- marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the
- number or order of execution of this <tt>load</tt> with other <a
- href="#volatile">volatile operations</a>.</p>
-
-<p>If the <code>load</code> is marked as <code>atomic</code>, it takes an extra
- <a href="#ordering">ordering</a> and optional <code>singlethread</code>
- argument. The <code>release</code> and <code>acq_rel</code> orderings are
- not valid on <code>load</code> instructions. Atomic loads produce <a
- href="#memorymodel">defined</a> results when they may see multiple atomic
- stores. The type of the pointee must be an integer type whose bit width
- is a power of two greater than or equal to eight and less than or equal
- to a target-specific size limit. <code>align</code> must be explicitly
- specified on atomic loads, and the load has undefined behavior if the
- alignment is not set to a value which is at least the size in bytes of
- the pointee. <code>!nontemporal</code> does not have any defined semantics
- for atomic loads.</p>
-
-<p>The optional constant <tt>align</tt> argument specifies the alignment of the
- operation (that is, the alignment of the memory address). A value of 0 or an
- omitted <tt>align</tt> argument means that the operation has the abi
- alignment for the target. It is the responsibility of the code emitter to
- ensure that the alignment information is correct. Overestimating the
- alignment results in undefined behavior. Underestimating the alignment may
- produce less efficient code. An alignment of 1 is always safe.</p>
-
-<p>The optional <tt>!nontemporal</tt> metadata must reference a single
- metatadata name <index> corresponding to a metadata node with
- one <tt>i32</tt> entry of value 1. The existence of
- the <tt>!nontemporal</tt> metatadata on the instruction tells the optimizer
- and code generator that this load is not expected to be reused in the cache.
- The code generator may select special instructions to save cache bandwidth,
- such as the <tt>MOVNT</tt> instruction on x86.</p>
-
-<p>The optional <tt>!invariant.load</tt> metadata must reference a single
- metatadata name <index> corresponding to a metadata node with no
- entries. The existence of the <tt>!invariant.load</tt> metatadata on the
- instruction tells the optimizer and code generator that this load address
- points to memory which does not change value during program execution.
- The optimizer may then move this load around, for example, by hoisting it
- out of loops using loop invariant code motion.</p>
-
-<h5>Semantics:</h5>
-<p>The location of memory pointed to is loaded. If the value being loaded is of
- scalar type then the number of bytes read does not exceed the minimum number
- of bytes needed to hold all bits of the type. For example, loading an
- <tt>i24</tt> reads at most three bytes. When loading a value of a type like
- <tt>i20</tt> with a size that is not an integral number of bytes, the result
- is undefined if the value was not originally written using a store of the
- same type.</p>
-
-<h5>Examples:</h5>
-<pre>
- %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
- <a href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i>
- %val = load i32* %ptr <i>; yields {i32}:val = i32 3</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_store">'<tt>store</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i>
- store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> <i>; yields {void}</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>store</tt>' instruction is used to write to memory.</p>
-
-<h5>Arguments:</h5>
-<p>There are two arguments to the '<tt>store</tt>' instruction: a value to store
- and an address at which to store it. The type of the
- '<tt><pointer></tt>' operand must be a pointer to
- the <a href="#t_firstclass">first class</a> type of the
- '<tt><value></tt>' operand. If the <tt>store</tt> is marked as
- <tt>volatile</tt>, then the optimizer is not allowed to modify the number or
- order of execution of this <tt>store</tt> with other <a
- href="#volatile">volatile operations</a>.</p>
-
-<p>If the <code>store</code> is marked as <code>atomic</code>, it takes an extra
- <a href="#ordering">ordering</a> and optional <code>singlethread</code>
- argument. The <code>acquire</code> and <code>acq_rel</code> orderings aren't
- valid on <code>store</code> instructions. Atomic loads produce <a
- href="#memorymodel">defined</a> results when they may see multiple atomic
- stores. The type of the pointee must be an integer type whose bit width
- is a power of two greater than or equal to eight and less than or equal
- to a target-specific size limit. <code>align</code> must be explicitly
- specified on atomic stores, and the store has undefined behavior if the
- alignment is not set to a value which is at least the size in bytes of
- the pointee. <code>!nontemporal</code> does not have any defined semantics
- for atomic stores.</p>
-
-<p>The optional constant "align" argument specifies the alignment of the
- operation (that is, the alignment of the memory address). A value of 0 or an
- omitted "align" argument means that the operation has the abi
- alignment for the target. It is the responsibility of the code emitter to
- ensure that the alignment information is correct. Overestimating the
- alignment results in an undefined behavior. Underestimating the alignment may
- produce less efficient code. An alignment of 1 is always safe.</p>
-
-<p>The optional !nontemporal metadata must reference a single metatadata
- name <index> corresponding to a metadata node with one i32 entry of
- value 1. The existence of the !nontemporal metatadata on the
- instruction tells the optimizer and code generator that this load is
- not expected to be reused in the cache. The code generator may
- select special instructions to save cache bandwidth, such as the
- MOVNT instruction on x86.</p>
-
-
-<h5>Semantics:</h5>
-<p>The contents of memory are updated to contain '<tt><value></tt>' at the
- location specified by the '<tt><pointer></tt>' operand. If
- '<tt><value></tt>' is of scalar type then the number of bytes written
- does not exceed the minimum number of bytes needed to hold all bits of the
- type. For example, storing an <tt>i24</tt> writes at most three bytes. When
- writing a value of a type like <tt>i20</tt> with a size that is not an
- integral number of bytes, it is unspecified what happens to the extra bits
- that do not belong to the type, but they will typically be overwritten.</p>
-
-<h5>Example:</h5>
-<pre>
- %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
- store i32 3, i32* %ptr <i>; yields {void}</i>
- %val = <a href="#i_load">load</a> i32* %ptr <i>; yields {i32}:val = i32 3</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
-<a name="i_fence">'<tt>fence</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- fence [singlethread] <ordering> <i>; yields {void}</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fence</tt>' instruction is used to introduce happens-before edges
-between operations.</p>
-
-<h5>Arguments:</h5> <p>'<code>fence</code>' instructions take an <a
-href="#ordering">ordering</a> argument which defines what
-<i>synchronizes-with</i> edges they add. They can only be given
-<code>acquire</code>, <code>release</code>, <code>acq_rel</code>, and
-<code>seq_cst</code> orderings.</p>
-
-<h5>Semantics:</h5>
-<p>A fence <var>A</var> which has (at least) <code>release</code> ordering
-semantics <i>synchronizes with</i> a fence <var>B</var> with (at least)
-<code>acquire</code> ordering semantics if and only if there exist atomic
-operations <var>X</var> and <var>Y</var>, both operating on some atomic object
-<var>M</var>, such that <var>A</var> is sequenced before <var>X</var>,
-<var>X</var> modifies <var>M</var> (either directly or through some side effect
-of a sequence headed by <var>X</var>), <var>Y</var> is sequenced before
-<var>B</var>, and <var>Y</var> observes <var>M</var>. This provides a
-<i>happens-before</i> dependency between <var>A</var> and <var>B</var>. Rather
-than an explicit <code>fence</code>, one (but not both) of the atomic operations
-<var>X</var> or <var>Y</var> might provide a <code>release</code> or
-<code>acquire</code> (resp.) ordering constraint and still
-<i>synchronize-with</i> the explicit <code>fence</code> and establish the
-<i>happens-before</i> edge.</p>
-
-<p>A <code>fence</code> which has <code>seq_cst</code> ordering, in addition to
-having both <code>acquire</code> and <code>release</code> semantics specified
-above, participates in the global program order of other <code>seq_cst</code>
-operations and/or fences.</p>
-
-<p>The optional "<a href="#singlethread"><code>singlethread</code></a>" argument
-specifies that the fence only synchronizes with other fences in the same
-thread. (This is useful for interacting with signal handlers.)</p>
-
-<h5>Example:</h5>
-<pre>
- fence acquire <i>; yields {void}</i>
- fence singlethread seq_cst <i>; yields {void}</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
-<a name="i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>cmpxchg</tt>' instruction is used to atomically modify memory.
-It loads a value in memory and compares it to a given value. If they are
-equal, it stores a new value into the memory.</p>
-
-<h5>Arguments:</h5>
-<p>There are three arguments to the '<code>cmpxchg</code>' instruction: an
-address to operate on, a value to compare to the value currently be at that
-address, and a new value to place at that address if the compared values are
-equal. The type of '<var><cmp></var>' must be an integer type whose
-bit width is a power of two greater than or equal to eight and less than
-or equal to a target-specific size limit. '<var><cmp></var>' and
-'<var><new></var>' must have the same type, and the type of
-'<var><pointer></var>' must be a pointer to that type. If the
-<code>cmpxchg</code> is marked as <code>volatile</code>, then the
-optimizer is not allowed to modify the number or order of execution
-of this <code>cmpxchg</code> with other <a href="#volatile">volatile
-operations</a>.</p>
-
-<!-- FIXME: Extend allowed types. -->
-
-<p>The <a href="#ordering"><var>ordering</var></a> argument specifies how this
-<code>cmpxchg</code> synchronizes with other atomic operations.</p>
-
-<p>The optional "<code>singlethread</code>" argument declares that the
-<code>cmpxchg</code> is only atomic with respect to code (usually signal
-handlers) running in the same thread as the <code>cmpxchg</code>. Otherwise the
-cmpxchg is atomic with respect to all other code in the system.</p>
-
-<p>The pointer passed into cmpxchg must have alignment greater than or equal to
-the size in memory of the operand.
-
-<h5>Semantics:</h5>
-<p>The contents of memory at the location specified by the
-'<tt><pointer></tt>' operand is read and compared to
-'<tt><cmp></tt>'; if the read value is the equal,
-'<tt><new></tt>' is written. The original value at the location
-is returned.
-
-<p>A successful <code>cmpxchg</code> is a read-modify-write instruction for the
-purpose of identifying <a href="#release_sequence">release sequences</a>. A
-failed <code>cmpxchg</code> is equivalent to an atomic load with an ordering
-parameter determined by dropping any <code>release</code> part of the
-<code>cmpxchg</code>'s ordering.</p>
-
-<!--
-FIXME: Is compare_exchange_weak() necessary? (Consider after we've done
-optimization work on ARM.)
-
-FIXME: Is a weaker ordering constraint on failure helpful in practice?
--->
-
-<h5>Example:</h5>
-<pre>
-entry:
- %orig = atomic <a href="#i_load">load</a> i32* %ptr unordered <i>; yields {i32}</i>
- <a href="#i_br">br</a> label %loop
-
-loop:
- %cmp = <a href="#i_phi">phi</a> i32 [ %orig, %entry ], [%old, %loop]
- %squared = <a href="#i_mul">mul</a> i32 %cmp, %cmp
- %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared <i>; yields {i32}</i>
- %success = <a href="#i_icmp">icmp</a> eq i32 %cmp, %old
- <a href="#i_br">br</a> i1 %success, label %done, label %loop
-
-done:
- ...
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
-<a name="i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> <i>; yields {ty}</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>atomicrmw</tt>' instruction is used to atomically modify memory.</p>
-
-<h5>Arguments:</h5>
-<p>There are three arguments to the '<code>atomicrmw</code>' instruction: an
-operation to apply, an address whose value to modify, an argument to the
-operation. The operation must be one of the following keywords:</p>
-<ul>
- <li>xchg</li>
- <li>add</li>
- <li>sub</li>
- <li>and</li>
- <li>nand</li>
- <li>or</li>
- <li>xor</li>
- <li>max</li>
- <li>min</li>
- <li>umax</li>
- <li>umin</li>
-</ul>
-
-<p>The type of '<var><value></var>' must be an integer type whose
-bit width is a power of two greater than or equal to eight and less than
-or equal to a target-specific size limit. The type of the
-'<code><pointer></code>' operand must be a pointer to that type.
-If the <code>atomicrmw</code> is marked as <code>volatile</code>, then the
-optimizer is not allowed to modify the number or order of execution of this
-<code>atomicrmw</code> with other <a href="#volatile">volatile
- operations</a>.</p>
-
-<!-- FIXME: Extend allowed types. -->
-
-<h5>Semantics:</h5>
-<p>The contents of memory at the location specified by the
-'<tt><pointer></tt>' operand are atomically read, modified, and written
-back. The original value at the location is returned. The modification is
-specified by the <var>operation</var> argument:</p>
-
-<ul>
- <li>xchg: <code>*ptr = val</code></li>
- <li>add: <code>*ptr = *ptr + val</code></li>
- <li>sub: <code>*ptr = *ptr - val</code></li>
- <li>and: <code>*ptr = *ptr & val</code></li>
- <li>nand: <code>*ptr = ~(*ptr & val)</code></li>
- <li>or: <code>*ptr = *ptr | val</code></li>
- <li>xor: <code>*ptr = *ptr ^ val</code></li>
- <li>max: <code>*ptr = *ptr > val ? *ptr : val</code> (using a signed comparison)</li>
- <li>min: <code>*ptr = *ptr < val ? *ptr : val</code> (using a signed comparison)</li>
- <li>umax: <code>*ptr = *ptr > val ? *ptr : val</code> (using an unsigned comparison)</li>
- <li>umin: <code>*ptr = *ptr < val ? *ptr : val</code> (using an unsigned comparison)</li>
-</ul>
-
-<h5>Example:</h5>
-<pre>
- %old = atomicrmw add i32* %ptr, i32 1 acquire <i>; yields {i32}</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
- <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}*
- <result> = getelementptr <ptr vector> ptrval, <vector index type> idx
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
- subelement of an <a href="#t_aggregate">aggregate</a> data structure.
- It performs address calculation only and does not access memory.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is always a pointer or a vector of pointers,
- and forms the basis of the
- calculation. The remaining arguments are indices that indicate which of the
- elements of the aggregate object are indexed. The interpretation of each
- index is dependent on the type being indexed into. The first index always
- indexes the pointer value given as the first argument, the second index
- indexes a value of the type pointed to (not necessarily the value directly
- pointed to, since the first index can be non-zero), etc. The first type
- indexed into must be a pointer value, subsequent types can be arrays,
- vectors, and structs. Note that subsequent types being indexed into
- can never be pointers, since that would require loading the pointer before
- continuing calculation.</p>
-
-<p>The type of each index argument depends on the type it is indexing into.
- When indexing into a (optionally packed) structure, only <tt>i32</tt>
- integer <b>constants</b> are allowed (when using a vector of indices they
- must all be the <b>same</b> <tt>i32</tt> integer constant). When indexing
- into an array, pointer or vector, integers of any width are allowed, and
- they are not required to be constant. These integers are treated as signed
- values where relevant.</p>
-
-<p>For example, let's consider a C code fragment and how it gets compiled to
- LLVM:</p>
-
-<pre class="doc_code">
-struct RT {
- char A;
- int B[10][20];
- char C;
-};
-struct ST {
- int X;
- double Y;
- struct RT Z;
-};
-
-int *foo(struct ST *s) {
- return &s[1].Z.B[5][13];
-}
-</pre>
-
-<p>The LLVM code generated by Clang is:</p>
-
-<pre class="doc_code">
-%struct.RT = <a href="#namedtypes">type</a> { i8, [10 x [20 x i32]], i8 }
-%struct.ST = <a href="#namedtypes">type</a> { i32, double, %struct.RT }
-
-define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp {
-entry:
- %arrayidx = getelementptr inbounds %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13
- ret i32* %arrayidx
-}
-</pre>
-
-<h5>Semantics:</h5>
-<p>In the example above, the first index is indexing into the
- '<tt>%struct.ST*</tt>' type, which is a pointer, yielding a
- '<tt>%struct.ST</tt>' = '<tt>{ i32, double, %struct.RT }</tt>' type, a
- structure. The second index indexes into the third element of the structure,
- yielding a '<tt>%struct.RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], i8 }</tt>'
- type, another structure. The third index indexes into the second element of
- the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an array. The
- two dimensions of the array are subscripted into, yielding an '<tt>i32</tt>'
- type. The '<tt>getelementptr</tt>' instruction returns a pointer to this
- element, thus computing a value of '<tt>i32*</tt>' type.</p>
-
-<p>Note that it is perfectly legal to index partially through a structure,
- returning a pointer to an inner element. Because of this, the LLVM code for
- the given testcase is equivalent to:</p>
-
-<pre class="doc_code">
-define i32* @foo(%struct.ST* %s) {
- %t1 = getelementptr %struct.ST* %s, i32 1 <i>; yields %struct.ST*:%t1</i>
- %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2 <i>; yields %struct.RT*:%t2</i>
- %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i>
- %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i>
- %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i>
- ret i32* %t5
-}
-</pre>
-
-<p>If the <tt>inbounds</tt> keyword is present, the result value of the
- <tt>getelementptr</tt> is a <a href="#poisonvalues">poison value</a> if the
- base pointer is not an <i>in bounds</i> address of an allocated object,
- or if any of the addresses that would be formed by successive addition of
- the offsets implied by the indices to the base address with infinitely
- precise signed arithmetic are not an <i>in bounds</i> address of that
- allocated object. The <i>in bounds</i> addresses for an allocated object
- are all the addresses that point into the object, plus the address one
- byte past the end.
- In cases where the base is a vector of pointers the <tt>inbounds</tt> keyword
- applies to each of the computations element-wise. </p>
-
-<p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
- the base address with silently-wrapping two's complement arithmetic. If the
- offsets have a different width from the pointer, they are sign-extended or
- truncated to the width of the pointer. The result value of the
- <tt>getelementptr</tt> may be outside the object pointed to by the base
- pointer. The result value may not necessarily be used to access memory
- though, even if it happens to point into allocated storage. See the
- <a href="#pointeraliasing">Pointer Aliasing Rules</a> section for more
- information.</p>
-
-<p>The getelementptr instruction is often confusing. For some more insight into
- how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
-
-<h5>Example:</h5>
-<pre>
- <i>; yields [12 x i8]*:aptr</i>
- %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
- <i>; yields i8*:vptr</i>
- %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1
- <i>; yields i8*:eptr</i>
- %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
- <i>; yields i32*:iptr</i>
- %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
-</pre>
-
-<p>In cases where the pointer argument is a vector of pointers, each index must
- be a vector with the same number of elements. For example: </p>
-<pre class="doc_code">
- %A = getelementptr <4 x i8*> %ptrs, <4 x i64> %offsets,
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="convertops">Conversion Operations</a>
-</h3>
-
-<div>
-
-<p>The instructions in this category are the conversion instructions (casting)
- which all take a single operand and a type. They perform various bit
- conversions on the operand.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = trunc <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>trunc</tt>' instruction truncates its operand to the
- type <tt>ty2</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>trunc</tt>' instruction takes a value to trunc, and a type to trunc it to.
- Both types must be of <a href="#t_integer">integer</a> types, or vectors
- of the same number of integers.
- The bit size of the <tt>value</tt> must be larger than
- the bit size of the destination type, <tt>ty2</tt>.
- Equal sized types are not allowed.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>trunc</tt>' instruction truncates the high order bits
- in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the
- source size must be larger than the destination size, <tt>trunc</tt> cannot
- be a <i>no-op cast</i>. It will always truncate bits.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = trunc i32 257 to i8 <i>; yields i8:1</i>
- %Y = trunc i32 123 to i1 <i>; yields i1:true</i>
- %Z = trunc i32 122 to i1 <i>; yields i1:false</i>
- %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> <i>; yields <i8 8, i8 7></i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = zext <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>zext</tt>' instruction zero extends its operand to type
- <tt>ty2</tt>.</p>
-
-
-<h5>Arguments:</h5>
-<p>The '<tt>zext</tt>' instruction takes a value to cast, and a type to cast it to.
- Both types must be of <a href="#t_integer">integer</a> types, or vectors
- of the same number of integers.
- The bit size of the <tt>value</tt> must be smaller than
- the bit size of the destination type,
- <tt>ty2</tt>.</p>
-
-<h5>Semantics:</h5>
-<p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
- bits until it reaches the size of the destination type, <tt>ty2</tt>.</p>
-
-<p>When zero extending from i1, the result will always be either 0 or 1.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = zext i32 257 to i64 <i>; yields i64:257</i>
- %Y = zext i1 true to i32 <i>; yields i32:1</i>
- %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = sext <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>sext</tt>' instruction takes a value to cast, and a type to cast it to.
- Both types must be of <a href="#t_integer">integer</a> types, or vectors
- of the same number of integers.
- The bit size of the <tt>value</tt> must be smaller than
- the bit size of the destination type,
- <tt>ty2</tt>.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
- bit (highest order bit) of the <tt>value</tt> until it reaches the bit size
- of the type <tt>ty2</tt>.</p>
-
-<p>When sign extending from i1, the extension always results in -1 or 0.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = sext i8 -1 to i16 <i>; yields i16 :65535</i>
- %Y = sext i1 true to i32 <i>; yields i32:-1</i>
- %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fptrunc <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
- <tt>ty2</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
- point</a> value to cast and a <a href="#t_floating">floating point</a> type
- to cast it to. The size of <tt>value</tt> must be larger than the size of
- <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
- <i>no-op cast</i>.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
- <a href="#t_floating">floating point</a> type to a smaller
- <a href="#t_floating">floating point</a> type. If the value cannot fit
- within the destination type, <tt>ty2</tt>, then the results are
- undefined.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = fptrunc double 123.0 to float <i>; yields float:123.0</i>
- %Y = fptrunc double 1.0E+300 to float <i>; yields undefined</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fpext <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
- floating point value.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>fpext</tt>' instruction takes a
- <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and
- a <a href="#t_floating">floating point</a> type to cast it to. The source
- type must be smaller than the destination type.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
- <a href="#t_floating">floating point</a> type to a larger
- <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
- used to make a <i>no-op cast</i> because it always changes bits. Use
- <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = fpext float 3.125 to double <i>; yields double:3.125000e+00</i>
- %Y = fpext double %X to fp128 <i>; yields fp128:0xL00000000000000004000900000000000</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fptoui <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its
- unsigned integer equivalent of type <tt>ty2</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a
- scalar or vector <a href="#t_floating">floating point</a> value, and a type
- to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
- type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
- vector integer type with the same number of elements as <tt>ty</tt></p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>fptoui</tt>' instruction converts its
- <a href="#t_floating">floating point</a> operand into the nearest (rounding
- towards zero) unsigned integer value. If the value cannot fit
- in <tt>ty2</tt>, the results are undefined.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = fptoui double 123.0 to i32 <i>; yields i32:123</i>
- %Y = fptoui float 1.0E+300 to i1 <i>; yields undefined:1</i>
- %Z = fptoui float 1.04E+17 to i8 <i>; yields undefined:1</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fptosi <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fptosi</tt>' instruction converts
- <a href="#t_floating">floating point</a> <tt>value</tt> to
- type <tt>ty2</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
- scalar or vector <a href="#t_floating">floating point</a> value, and a type
- to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
- type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
- vector integer type with the same number of elements as <tt>ty</tt></p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>fptosi</tt>' instruction converts its
- <a href="#t_floating">floating point</a> operand into the nearest (rounding
- towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
- the results are undefined.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = fptosi double -123.0 to i32 <i>; yields i32:-123</i>
- %Y = fptosi float 1.0E-247 to i1 <i>; yields undefined:1</i>
- %Z = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = uitofp <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
- integer and converts that value to the <tt>ty2</tt> type.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a
- scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
- it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
- type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
- floating point type with the same number of elements as <tt>ty</tt></p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
- integer quantity and converts it to the corresponding floating point
- value. If the value cannot fit in the floating point value, the results are
- undefined.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = uitofp i32 257 to float <i>; yields float:257.0</i>
- %Y = uitofp i8 -1 to double <i>; yields double:255.0</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = sitofp <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer
- and converts that value to the <tt>ty2</tt> type.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a
- scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
- it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
- type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
- floating point type with the same number of elements as <tt>ty</tt></p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer
- quantity and converts it to the corresponding floating point value. If the
- value cannot fit in the floating point value, the results are undefined.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = sitofp i32 257 to float <i>; yields float:257.0</i>
- %Y = sitofp i8 -1 to double <i>; yields double:-1.0</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = ptrtoint <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>ptrtoint</tt>' instruction converts the pointer or a vector of
- pointers <tt>value</tt> to
- the integer (or vector of integers) type <tt>ty2</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
- must be a a value of type <a href="#t_pointer">pointer</a> or a vector of
- pointers, and a type to cast it to
- <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> or a vector
- of integers type.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
- <tt>ty2</tt> by interpreting the pointer value as an integer and either
- truncating or zero extending that value to the size of the integer type. If
- <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
- <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
- are the same size, then nothing is done (<i>no-op cast</i>) other than a type
- change.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = ptrtoint i32* %P to i8 <i>; yields truncation on 32-bit architecture</i>
- %Y = ptrtoint i32* %P to i64 <i>; yields zero extension on 32-bit architecture</i>
- %Z = ptrtoint <4 x i32*> %P to <4 x i64><i>; yields vector zero extension for a vector of addresses on 32-bit architecture</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = inttoptr <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a
- pointer type, <tt>ty2</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a>
- value to cast, and a type to cast it to, which must be a
- <a href="#t_pointer">pointer</a> type.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
- <tt>ty2</tt> by applying either a zero extension or a truncation depending on
- the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
- size of a pointer then a truncation is done. If <tt>value</tt> is smaller
- than the size of a pointer then a zero extension is done. If they are the
- same size, nothing is done (<i>no-op cast</i>).</p>
-
-<h5>Example:</h5>
-<pre>
- %X = inttoptr i32 255 to i32* <i>; yields zero extension on 64-bit architecture</i>
- %Y = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i>
- %Z = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i>
- %Z = inttoptr <4 x i32> %G to <4 x i8*><i>; yields truncation of vector G to four pointers</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = bitcast <ty> <value> to <ty2> <i>; yields ty2</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
- <tt>ty2</tt> without changing any bits.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be a
- non-aggregate first class value, and a type to cast it to, which must also be
- a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes
- of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be
- identical. If the source type is a pointer, the destination type must also be
- a pointer. This instruction supports bitwise conversion of vectors to
- integers and to vectors of other types (as long as they have the same
- size).</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
- <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
- this conversion. The conversion is done as if the <tt>value</tt> had been
- stored to memory and read back as type <tt>ty2</tt>.
- Pointer (or vector of pointers) types may only be converted to other pointer
- (or vector of pointers) types with this instruction. To convert
- pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or
- <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = bitcast i8 255 to i8 <i>; yields i8 :-1</i>
- %Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i>
- %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i>
- %Z = bitcast <2 x i32*> %V to <2 x i64*> <i>; yields <2 x i64*></i>
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="otherops">Other Operations</a>
-</h3>
-
-<div>
-
-<p>The instructions in this category are the "miscellaneous" instructions, which
- defy better classification.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = icmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of
- boolean values based on comparison of its two integer, integer vector,
- pointer, or pointer vector operands.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
- the condition code indicating the kind of comparison to perform. It is not a
- value, just a keyword. The possible condition code are:</p>
-
-<ol>
- <li><tt>eq</tt>: equal</li>
- <li><tt>ne</tt>: not equal </li>
- <li><tt>ugt</tt>: unsigned greater than</li>
- <li><tt>uge</tt>: unsigned greater or equal</li>
- <li><tt>ult</tt>: unsigned less than</li>
- <li><tt>ule</tt>: unsigned less or equal</li>
- <li><tt>sgt</tt>: signed greater than</li>
- <li><tt>sge</tt>: signed greater or equal</li>
- <li><tt>slt</tt>: signed less than</li>
- <li><tt>sle</tt>: signed less or equal</li>
-</ol>
-
-<p>The remaining two arguments must be <a href="#t_integer">integer</a> or
- <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a>
- typed. They must also be identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the
- condition code given as <tt>cond</tt>. The comparison performed always yields
- either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt>
- result, as follows:</p>
-
-<ol>
- <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
- <tt>false</tt> otherwise. No sign interpretation is necessary or
- performed.</li>
-
- <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
- <tt>false</tt> otherwise. No sign interpretation is necessary or
- performed.</li>
-
- <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
- <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
-
- <li><tt>uge</tt>: interprets the operands as unsigned values and yields
- <tt>true</tt> if <tt>op1</tt> is greater than or equal
- to <tt>op2</tt>.</li>
-
- <li><tt>ult</tt>: interprets the operands as unsigned values and yields
- <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
-
- <li><tt>ule</tt>: interprets the operands as unsigned values and yields
- <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
-
- <li><tt>sgt</tt>: interprets the operands as signed values and yields
- <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
-
- <li><tt>sge</tt>: interprets the operands as signed values and yields
- <tt>true</tt> if <tt>op1</tt> is greater than or equal
- to <tt>op2</tt>.</li>
-
- <li><tt>slt</tt>: interprets the operands as signed values and yields
- <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
-
- <li><tt>sle</tt>: interprets the operands as signed values and yields
- <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
-</ol>
-
-<p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
- values are compared as if they were integers.</p>
-
-<p>If the operands are integer vectors, then they are compared element by
- element. The result is an <tt>i1</tt> vector with the same number of elements
- as the values being compared. Otherwise, the result is an <tt>i1</tt>.</p>
-
-<h5>Example:</h5>
-<pre>
- <result> = icmp eq i32 4, 5 <i>; yields: result=false</i>
- <result> = icmp ne float* %X, %X <i>; yields: result=false</i>
- <result> = icmp ult i16 4, 5 <i>; yields: result=true</i>
- <result> = icmp sgt i16 4, 5 <i>; yields: result=false</i>
- <result> = icmp ule i16 -4, 5 <i>; yields: result=false</i>
- <result> = icmp sge i16 4, 5 <i>; yields: result=false</i>
-</pre>
-
-<p>Note that the code generator does not yet support vector types with
- the <tt>icmp</tt> instruction.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = fcmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean
- values based on comparison of its operands.</p>
-
-<p>If the operands are floating point scalars, then the result type is a boolean
-(<a href="#t_integer"><tt>i1</tt></a>).</p>
-
-<p>If the operands are floating point vectors, then the result type is a vector
- of boolean with the same number of elements as the operands being
- compared.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
- the condition code indicating the kind of comparison to perform. It is not a
- value, just a keyword. The possible condition code are:</p>
-
-<ol>
- <li><tt>false</tt>: no comparison, always returns false</li>
- <li><tt>oeq</tt>: ordered and equal</li>
- <li><tt>ogt</tt>: ordered and greater than </li>
- <li><tt>oge</tt>: ordered and greater than or equal</li>
- <li><tt>olt</tt>: ordered and less than </li>
- <li><tt>ole</tt>: ordered and less than or equal</li>
- <li><tt>one</tt>: ordered and not equal</li>
- <li><tt>ord</tt>: ordered (no nans)</li>
- <li><tt>ueq</tt>: unordered or equal</li>
- <li><tt>ugt</tt>: unordered or greater than </li>
- <li><tt>uge</tt>: unordered or greater than or equal</li>
- <li><tt>ult</tt>: unordered or less than </li>
- <li><tt>ule</tt>: unordered or less than or equal</li>
- <li><tt>une</tt>: unordered or not equal</li>
- <li><tt>uno</tt>: unordered (either nans)</li>
- <li><tt>true</tt>: no comparison, always returns true</li>
-</ol>
-
-<p><i>Ordered</i> means that neither operand is a QNAN while
- <i>unordered</i> means that either operand may be a QNAN.</p>
-
-<p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either
- a <a href="#t_floating">floating point</a> type or
- a <a href="#t_vector">vector</a> of floating point type. They must have
- identical types.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt>
- according to the condition code given as <tt>cond</tt>. If the operands are
- vectors, then the vectors are compared element by element. Each comparison
- performed always yields an <a href="#t_integer">i1</a> result, as
- follows:</p>
-
-<ol>
- <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
-
- <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
- <tt>op1</tt> is equal to <tt>op2</tt>.</li>
-
- <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
- <tt>op1</tt> is greater than <tt>op2</tt>.</li>
-
- <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
- <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
-
- <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
- <tt>op1</tt> is less than <tt>op2</tt>.</li>
-
- <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
- <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
-
- <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
- <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
-
- <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
-
- <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
- <tt>op1</tt> is equal to <tt>op2</tt>.</li>
-
- <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
- <tt>op1</tt> is greater than <tt>op2</tt>.</li>
-
- <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
- <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
-
- <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
- <tt>op1</tt> is less than <tt>op2</tt>.</li>
-
- <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
- <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
-
- <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
- <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
-
- <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
-
- <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
-</ol>
-
-<h5>Example:</h5>
-<pre>
- <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i>
- <result> = fcmp one float 4.0, 5.0 <i>; yields: result=true</i>
- <result> = fcmp olt float 4.0, 5.0 <i>; yields: result=true</i>
- <result> = fcmp ueq double 1.0, 2.0 <i>; yields: result=false</i>
-</pre>
-
-<p>Note that the code generator does not yet support vector types with
- the <tt>fcmp</tt> instruction.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_phi">'<tt>phi</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = phi <ty> [ <val0>, <label0>], ...
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>phi</tt>' instruction is used to implement the φ node in the
- SSA graph representing the function.</p>
-
-<h5>Arguments:</h5>
-<p>The type of the incoming values is specified with the first type field. After
- this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
- one pair for each predecessor basic block of the current block. Only values
- of <a href="#t_firstclass">first class</a> type may be used as the value
- arguments to the PHI node. Only labels may be used as the label
- arguments.</p>
-
-<p>There must be no non-phi instructions between the start of a basic block and
- the PHI instructions: i.e. PHI instructions must be first in a basic
- block.</p>
-
-<p>For the purposes of the SSA form, the use of each incoming value is deemed to
- occur on the edge from the corresponding predecessor block to the current
- block (but after any definition of an '<tt>invoke</tt>' instruction's return
- value on the same edge).</p>
-
-<h5>Semantics:</h5>
-<p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
- specified by the pair corresponding to the predecessor basic block that
- executed just prior to the current block.</p>
-
-<h5>Example:</h5>
-<pre>
-Loop: ; Infinite loop that counts from 0 on up...
- %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
- %nextindvar = add i32 %indvar, 1
- br label %Loop
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_select">'<tt>select</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = select <i>selty</i> <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i>
-
- <i>selty</i> is either i1 or {<N x i1>}
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>select</tt>' instruction is used to choose one value based on a
- condition, without branching.</p>
-
-
-<h5>Arguments:</h5>
-<p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1'
- values indicating the condition, and two values of the
- same <a href="#t_firstclass">first class</a> type. If the val1/val2 are
- vectors and the condition is a scalar, then entire vectors are selected, not
- individual elements.</p>
-
-<h5>Semantics:</h5>
-<p>If the condition is an i1 and it evaluates to 1, the instruction returns the
- first value argument; otherwise, it returns the second value argument.</p>
-
-<p>If the condition is a vector of i1, then the value arguments must be vectors
- of the same size, and the selection is done element by element.</p>
-
-<h5>Example:</h5>
-<pre>
- %X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i>
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_call">'<tt>call</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = [tail] call [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] <ty> [<fnty>*] <fnptrval>(<function args>) [<a href="#fnattrs">fn attrs</a>]
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>call</tt>' instruction represents a simple function call.</p>
-
-<h5>Arguments:</h5>
-<p>This instruction requires several arguments:</p>
-
-<ol>
- <li>The optional "tail" marker indicates that the callee function does not
- access any allocas or varargs in the caller. Note that calls may be
- marked "tail" even if they do not occur before
- a <a href="#i_ret"><tt>ret</tt></a> instruction. If the "tail" marker is
- present, the function call is eligible for tail call optimization,
- but <a href="CodeGenerator.html#tailcallopt">might not in fact be
- optimized into a jump</a>. The code generator may optimize calls marked
- "tail" with either 1) automatic <a href="CodeGenerator.html#sibcallopt">
- sibling call optimization</a> when the caller and callee have
- matching signatures, or 2) forced tail call optimization when the
- following extra requirements are met:
- <ul>
- <li>Caller and callee both have the calling
- convention <tt>fastcc</tt>.</li>
- <li>The call is in tail position (ret immediately follows call and ret
- uses value of call or is void).</li>
- <li>Option <tt>-tailcallopt</tt> is enabled,
- or <code>llvm::GuaranteedTailCallOpt</code> is <code>true</code>.</li>
- <li><a href="CodeGenerator.html#tailcallopt">Platform specific
- constraints are met.</a></li>
- </ul>
- </li>
-
- <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
- convention</a> the call should use. If none is specified, the call
- defaults to using C calling conventions. The calling convention of the
- call must match the calling convention of the target function, or else the
- behavior is undefined.</li>
-
- <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
- return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
- '<tt>inreg</tt>' attributes are valid here.</li>
-
- <li>'<tt>ty</tt>': the type of the call instruction itself which is also the
- type of the return value. Functions that return no value are marked
- <tt><a href="#t_void">void</a></tt>.</li>
-
- <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value
- being invoked. The argument types must match the types implied by this
- signature. This type can be omitted if the function is not varargs and if
- the function type does not return a pointer to a function.</li>
-
- <li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
- be invoked. In most cases, this is a direct function invocation, but
- indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
- to function value.</li>
-
- <li>'<tt>function args</tt>': argument list whose types match the function
- signature argument types and parameter attributes. All arguments must be
- of <a href="#t_firstclass">first class</a> type. If the function
- signature indicates the function accepts a variable number of arguments,
- the extra arguments can be specified.</li>
-
- <li>The optional <a href="#fnattrs">function attributes</a> list. Only
- '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
- '<tt>readnone</tt>' attributes are valid here.</li>
-</ol>
-
-<h5>Semantics:</h5>
-<p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to
- a specified function, with its incoming arguments bound to the specified
- values. Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called
- function, control flow continues with the instruction after the function
- call, and the return value of the function is bound to the result
- argument.</p>
-
-<h5>Example:</h5>
-<pre>
- %retval = call i32 @test(i32 %argc)
- call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) <i>; yields i32</i>
- %X = tail call i32 @foo() <i>; yields i32</i>
- %Y = tail call <a href="#callingconv">fastcc</a> i32 @foo() <i>; yields i32</i>
- call void %foo(i8 97 signext)
-
- %struct.A = type { i32, i8 }
- %r = call %struct.A @foo() <i>; yields { 32, i8 }</i>
- %gr = extractvalue %struct.A %r, 0 <i>; yields i32</i>
- %gr1 = extractvalue %struct.A %r, 1 <i>; yields i8</i>
- %Z = call void @foo() noreturn <i>; indicates that %foo never returns normally</i>
- %ZZ = call zeroext i32 @bar() <i>; Return value is %zero extended</i>
-</pre>
-
-<p>llvm treats calls to some functions with names and arguments that match the
-standard C99 library as being the C99 library functions, and may perform
-optimizations or generate code for them under that assumption. This is
-something we'd like to change in the future to provide better support for
-freestanding environments and non-C-based languages.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <resultval> = va_arg <va_list*> <arglist>, <argty>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
- the "variable argument" area of a function call. It is used to implement the
- <tt>va_arg</tt> macro in C.</p>
-
-<h5>Arguments:</h5>
-<p>This instruction takes a <tt>va_list*</tt> value and the type of the
- argument. It returns a value of the specified argument type and increments
- the <tt>va_list</tt> to point to the next argument. The actual type
- of <tt>va_list</tt> is target specific.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type
- from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point
- to the next argument. For more information, see the variable argument
- handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
-
-<p>It is legal for this instruction to be called in a function which does not
- take a variable number of arguments, for example, the <tt>vfprintf</tt>
- function.</p>
-
-<p><tt>va_arg</tt> is an LLVM instruction instead of
- an <a href="#intrinsics">intrinsic function</a> because it takes a type as an
- argument.</p>
-
-<h5>Example:</h5>
-<p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
-
-<p>Note that the code generator does not yet fully support va_arg on many
- targets. Also, it does not currently support va_arg with aggregate types on
- any target.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="i_landingpad">'<tt>landingpad</tt>' Instruction</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+
- <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>*
-
- <clause> := catch <type> <value>
- <clause> := filter <array constant type> <array constant>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>landingpad</tt>' instruction is used by
- <a href="ExceptionHandling.html#overview">LLVM's exception handling
- system</a> to specify that a basic block is a landing pad — one where
- the exception lands, and corresponds to the code found in the
- <i><tt>catch</tt></i> portion of a <i><tt>try/catch</tt></i> sequence. It
- defines values supplied by the personality function (<tt>pers_fn</tt>) upon
- re-entry to the function. The <tt>resultval</tt> has the
- type <tt>resultty</tt>.</p>
-
-<h5>Arguments:</h5>
-<p>This instruction takes a <tt>pers_fn</tt> value. This is the personality
- function associated with the unwinding mechanism. The optional
- <tt>cleanup</tt> flag indicates that the landing pad block is a cleanup.</p>
-
-<p>A <tt>clause</tt> begins with the clause type — <tt>catch</tt>
- or <tt>filter</tt> — and contains the global variable representing the
- "type" that may be caught or filtered respectively. Unlike the
- <tt>catch</tt> clause, the <tt>filter</tt> clause takes an array constant as
- its argument. Use "<tt>[0 x i8**] undef</tt>" for a filter which cannot
- throw. The '<tt>landingpad</tt>' instruction must contain <em>at least</em>
- one <tt>clause</tt> or the <tt>cleanup</tt> flag.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>landingpad</tt>' instruction defines the values which are set by the
- personality function (<tt>pers_fn</tt>) upon re-entry to the function, and
- therefore the "result type" of the <tt>landingpad</tt> instruction. As with
- calling conventions, how the personality function results are represented in
- LLVM IR is target specific.</p>
-
-<p>The clauses are applied in order from top to bottom. If two
- <tt>landingpad</tt> instructions are merged together through inlining, the
- clauses from the calling function are appended to the list of clauses.
- When the call stack is being unwound due to an exception being thrown, the
- exception is compared against each <tt>clause</tt> in turn. If it doesn't
- match any of the clauses, and the <tt>cleanup</tt> flag is not set, then
- unwinding continues further up the call stack.</p>
-
-<p>The <tt>landingpad</tt> instruction has several restrictions:</p>
-
-<ul>
- <li>A landing pad block is a basic block which is the unwind destination of an
- '<tt>invoke</tt>' instruction.</li>
- <li>A landing pad block must have a '<tt>landingpad</tt>' instruction as its
- first non-PHI instruction.</li>
- <li>There can be only one '<tt>landingpad</tt>' instruction within the landing
- pad block.</li>
- <li>A basic block that is not a landing pad block may not include a
- '<tt>landingpad</tt>' instruction.</li>
- <li>All '<tt>landingpad</tt>' instructions in a function must have the same
- personality function.</li>
-</ul>
-
-<h5>Example:</h5>
-<pre>
- ;; A landing pad which can catch an integer.
- %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
- catch i8** @_ZTIi
- ;; A landing pad that is a cleanup.
- %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
- cleanup
- ;; A landing pad which can catch an integer and can only throw a double.
- %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
- catch i8** @_ZTIi
- filter [1 x i8**] [@_ZTId]
-</pre>
-
-</div>
-
-</div>
-
-</div>
-
-<!-- *********************************************************************** -->
-<h2><a name="intrinsics">Intrinsic Functions</a></h2>
-<!-- *********************************************************************** -->
-
-<div>
-
-<p>LLVM supports the notion of an "intrinsic function". These functions have
- well known names and semantics and are required to follow certain
- restrictions. Overall, these intrinsics represent an extension mechanism for
- the LLVM language that does not require changing all of the transformations
- in LLVM when adding to the language (or the bitcode reader/writer, the
- parser, etc...).</p>
-
-<p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
- prefix is reserved in LLVM for intrinsic names; thus, function names may not
- begin with this prefix. Intrinsic functions must always be external
- functions: you cannot define the body of intrinsic functions. Intrinsic
- functions may only be used in call or invoke instructions: it is illegal to
- take the address of an intrinsic function. Additionally, because intrinsic
- functions are part of the LLVM language, it is required if any are added that
- they be documented here.</p>
-
-<p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a
- family of functions that perform the same operation but on different data
- types. Because LLVM can represent over 8 million different integer types,
- overloading is used commonly to allow an intrinsic function to operate on any
- integer type. One or more of the argument types or the result type can be
- overloaded to accept any integer type. Argument types may also be defined as
- exactly matching a previous argument's type or the result type. This allows
- an intrinsic function which accepts multiple arguments, but needs all of them
- to be of the same type, to only be overloaded with respect to a single
- argument or the result.</p>
-
-<p>Overloaded intrinsics will have the names of its overloaded argument types
- encoded into its function name, each preceded by a period. Only those types
- which are overloaded result in a name suffix. Arguments whose type is matched
- against another type do not. For example, the <tt>llvm.ctpop</tt> function
- can take an integer of any width and returns an integer of exactly the same
- integer width. This leads to a family of functions such as
- <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29
- %val)</tt>. Only one type, the return type, is overloaded, and only one type
- suffix is required. Because the argument's type is matched against the return
- type, it does not require its own name suffix.</p>
-
-<p>To learn how to add an intrinsic function, please see the
- <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_varargs">Variable Argument Handling Intrinsics</a>
-</h3>
-
-<div>
-
-<p>Variable argument support is defined in LLVM with
- the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
- intrinsic functions. These functions are related to the similarly named
- macros defined in the <tt><stdarg.h></tt> header file.</p>
-
-<p>All of these functions operate on arguments that use a target-specific value
- type "<tt>va_list</tt>". The LLVM assembly language reference manual does
- not define what this type is, so all transformations should be prepared to
- handle these functions regardless of the type used.</p>
-
-<p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
- instruction and the variable argument handling intrinsic functions are
- used.</p>
-
-<pre class="doc_code">
-define i32 @test(i32 %X, ...) {
- ; Initialize variable argument processing
- %ap = alloca i8*
- %ap2 = bitcast i8** %ap to i8*
- call void @llvm.va_start(i8* %ap2)
-
- ; Read a single integer argument
- %tmp = va_arg i8** %ap, i32
-
- ; Demonstrate usage of llvm.va_copy and llvm.va_end
- %aq = alloca i8*
- %aq2 = bitcast i8** %aq to i8*
- call void @llvm.va_copy(i8* %aq2, i8* %ap2)
- call void @llvm.va_end(i8* %aq2)
-
- ; Stop processing of arguments.
- call void @llvm.va_end(i8* %ap2)
- ret i32 %tmp
-}
-
-declare void @llvm.va_start(i8*)
-declare void @llvm.va_copy(i8*, i8*)
-declare void @llvm.va_end(i8*)
-</pre>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
-</h4>
-
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void %llvm.va_start(i8* <arglist>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*<arglist></tt>
- for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
- macro available in C. In a target-dependent way, it initializes
- the <tt>va_list</tt> element to which the argument points, so that the next
- call to <tt>va_arg</tt> will produce the first variable argument passed to
- the function. Unlike the C <tt>va_start</tt> macro, this intrinsic does not
- need to know the last argument of the function as the compiler can figure
- that out.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.va_end(i8* <arglist>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt>,
- which has been initialized previously
- with <tt><a href="#int_va_start">llvm.va_start</a></tt>
- or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
-
-<h5>Arguments:</h5>
-<p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
- macro available in C. In a target-dependent way, it destroys
- the <tt>va_list</tt> element to which the argument points. Calls
- to <a href="#int_va_start"><tt>llvm.va_start</tt></a>
- and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly
- with calls to <tt>llvm.va_end</tt>.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position
- from the source argument list to the destination argument list.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
- The second argument is a pointer to a <tt>va_list</tt> element to copy
- from.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
- macro available in C. In a target-dependent way, it copies the
- source <tt>va_list</tt> element into the destination <tt>va_list</tt>
- element. This intrinsic is necessary because
- the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be
- arbitrarily complex and require, for example, memory allocation.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
-</h3>
-
-<div>
-
-<p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage
-Collection</a> (GC) requires the implementation and generation of these
-intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC
-roots on the stack</a>, as well as garbage collector implementations that
-require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a>
-barriers. Front-ends for type-safe garbage collected languages should generate
-these intrinsics to make use of the LLVM garbage collectors. For more details,
-see <a href="GarbageCollection.html">Accurate Garbage Collection with
-LLVM</a>.</p>
-
-<p>The garbage collection intrinsics only operate on objects in the generic
- address space (address space zero).</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
- the code generator, and allows some metadata to be associated with it.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument specifies the address of a stack object that contains the
- root pointer. The second pointer (which must be either a constant or a
- global value address) contains the meta-data to be associated with the
- root.</p>
-
-<h5>Semantics:</h5>
-<p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc"
- location. At compile-time, the code generator generates information to allow
- the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>'
- intrinsic may only be used in a function which <a href="#gc">specifies a GC
- algorithm</a>.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
- locations, allowing garbage collector implementations that require read
- barriers.</p>
-
-<h5>Arguments:</h5>
-<p>The second argument is the address to read from, which should be an address
- allocated from the garbage collector. The first object is a pointer to the
- start of the referenced object, if needed by the language runtime (otherwise
- null).</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
- instruction, but may be replaced with substantially more complex code by the
- garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic
- may only be used in a function which <a href="#gc">specifies a GC
- algorithm</a>.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
- locations, allowing garbage collector implementations that require write
- barriers (such as generational or reference counting collectors).</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is the reference to store, the second is the start of the
- object to store it to, and the third is the address of the field of Obj to
- store to. If the runtime does not require a pointer to the object, Obj may
- be null.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
- instruction, but may be replaced with substantially more complex code by the
- garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic
- may only be used in a function which <a href="#gc">specifies a GC
- algorithm</a>.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_codegen">Code Generator Intrinsics</a>
-</h3>
-
-<div>
-
-<p>These intrinsics are provided by LLVM to expose special features that may
- only be implemented with code generator support.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i8 *@llvm.returnaddress(i32 <level>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
- target-specific value indicating the return address of the current function
- or one of its callers.</p>
-
-<h5>Arguments:</h5>
-<p>The argument to this intrinsic indicates which function to return the address
- for. Zero indicates the calling function, one indicates its caller, etc.
- The argument is <b>required</b> to be a constant integer value.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer
- indicating the return address of the specified call frame, or zero if it
- cannot be identified. The value returned by this intrinsic is likely to be
- incorrect or 0 for arguments other than zero, so it should only be used for
- debugging purposes.</p>
-
-<p>Note that calling this intrinsic does not prevent function inlining or other
- aggressive transformations, so the value returned may not be that of the
- obvious source-language caller.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i8* @llvm.frameaddress(i32 <level>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
- target-specific frame pointer value for the specified stack frame.</p>
-
-<h5>Arguments:</h5>
-<p>The argument to this intrinsic indicates which function to return the frame
- pointer for. Zero indicates the calling function, one indicates its caller,
- etc. The argument is <b>required</b> to be a constant integer value.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer
- indicating the frame address of the specified call frame, or zero if it
- cannot be identified. The value returned by this intrinsic is likely to be
- incorrect or 0 for arguments other than zero, so it should only be used for
- debugging purposes.</p>
-
-<p>Note that calling this intrinsic does not prevent function inlining or other
- aggressive transformations, so the value returned may not be that of the
- obvious source-language caller.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i8* @llvm.stacksave()
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state
- of the function stack, for use
- with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>. This is
- useful for implementing language features like scoped automatic variable
- sized arrays in C99.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic returns a opaque pointer value that can be passed
- to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>. When
- an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved
- from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack
- to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.
- In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the
- stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.stackrestore(i8* %ptr)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
- the function stack to the state it was in when the
- corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic
- executed. This is useful for implementing language features like scoped
- automatic variable sized arrays in C99.</p>
-
-<h5>Semantics:</h5>
-<p>See the description
- for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to
- insert a prefetch instruction if supported; otherwise, it is a noop.
- Prefetches have no effect on the behavior of the program but can change its
- performance characteristics.</p>
-
-<h5>Arguments:</h5>
-<p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the
- specifier determining if the fetch should be for a read (0) or write (1),
- and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
- locality, to (3) - extremely local keep in cache. The <tt>cache type</tt>
- specifies whether the prefetch is performed on the data (1) or instruction (0)
- cache. The <tt>rw</tt>, <tt>locality</tt> and <tt>cache type</tt> arguments
- must be constant integers.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic does not modify the behavior of the program. In particular,
- prefetches cannot trap and do not produce a value. On targets that support
- this intrinsic, the prefetch can provide hints to the processor cache for
- better performance.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.pcmarker(i32 <id>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program
- Counter (PC) in a region of code to simulators and other tools. The method
- is target specific, but it is expected that the marker will use exported
- symbols to transmit the PC of the marker. The marker makes no guarantees
- that it will remain with any specific instruction after optimizations. It is
- possible that the presence of a marker will inhibit optimizations. The
- intended use is to be inserted after optimizations to allow correlations of
- simulation runs.</p>
-
-<h5>Arguments:</h5>
-<p><tt>id</tt> is a numerical id identifying the marker.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic does not modify the behavior of the program. Backends that do
- not support this intrinsic may ignore it.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i64 @llvm.readcyclecounter()
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
- counter register (or similar low latency, high accuracy clocks) on those
- targets that support it. On X86, it should map to RDTSC. On Alpha, it
- should map to RPCC. As the backing counters overflow quickly (on the order
- of 9 seconds on alpha), this should only be used for small timings.</p>
-
-<h5>Semantics:</h5>
-<p>When directly supported, reading the cycle counter should not modify any
- memory. Implementations are allowed to either return a application specific
- value or a system wide value. On backends without support, this is lowered
- to a constant 0.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_libc">Standard C Library Intrinsics</a>
-</h3>
-
-<div>
-
-<p>LLVM provides intrinsics for a few important standard C library functions.
- These intrinsics allow source-language front-ends to pass information about
- the alignment of the pointer arguments to the code generator, providing
- opportunity for more efficient code generation.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any
- integer bit width and for different address spaces. Not all targets support
- all bit widths however.</p>
-
-<pre>
- declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
- i32 <len>, i32 <align>, i1 <isvolatile>)
- declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
- i64 <len>, i32 <align>, i1 <isvolatile>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
- source location to the destination location.</p>
-
-<p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
- intrinsics do not return a value, takes extra alignment/isvolatile arguments
- and the pointers can be in specified address spaces.</p>
-
-<h5>Arguments:</h5>
-
-<p>The first argument is a pointer to the destination, the second is a pointer
- to the source. The third argument is an integer argument specifying the
- number of bytes to copy, the fourth argument is the alignment of the
- source and destination locations, and the fifth is a boolean indicating a
- volatile access.</p>
-
-<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
- then the caller guarantees that both the source and destination pointers are
- aligned to that boundary.</p>
-
-<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
- <tt>llvm.memcpy</tt> call is a <a href="#volatile">volatile operation</a>.
- The detailed access behavior is not very cleanly specified and it is unwise
- to depend on it.</p>
-
-<h5>Semantics:</h5>
-
-<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
- source location to the destination location, which are not allowed to
- overlap. It copies "len" bytes of memory over. If the argument is known to
- be aligned to some boundary, this can be specified as the fourth argument,
- otherwise it should be set to 0 or 1.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
- width and for different address space. Not all targets support all bit
- widths however.</p>
-
-<pre>
- declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
- i32 <len>, i32 <align>, i1 <isvolatile>)
- declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
- i64 <len>, i32 <align>, i1 <isvolatile>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the
- source location to the destination location. It is similar to the
- '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to
- overlap.</p>
-
-<p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
- intrinsics do not return a value, takes extra alignment/isvolatile arguments
- and the pointers can be in specified address spaces.</p>
-
-<h5>Arguments:</h5>
-
-<p>The first argument is a pointer to the destination, the second is a pointer
- to the source. The third argument is an integer argument specifying the
- number of bytes to copy, the fourth argument is the alignment of the
- source and destination locations, and the fifth is a boolean indicating a
- volatile access.</p>
-
-<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
- then the caller guarantees that the source and destination pointers are
- aligned to that boundary.</p>
-
-<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
- <tt>llvm.memmove</tt> call is a <a href="#volatile">volatile operation</a>.
- The detailed access behavior is not very cleanly specified and it is unwise
- to depend on it.</p>
-
-<h5>Semantics:</h5>
-
-<p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the
- source location to the destination location, which may overlap. It copies
- "len" bytes of memory over. If the argument is known to be aligned to some
- boundary, this can be specified as the fourth argument, otherwise it should
- be set to 0 or 1.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit
- width and for different address spaces. However, not all targets support all
- bit widths.</p>
-
-<pre>
- declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>,
- i32 <len>, i32 <align>, i1 <isvolatile>)
- declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>,
- i64 <len>, i32 <align>, i1 <isvolatile>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a
- particular byte value.</p>
-
-<p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt>
- intrinsic does not return a value and takes extra alignment/volatile
- arguments. Also, the destination can be in an arbitrary address space.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is a pointer to the destination to fill, the second is the
- byte value with which to fill it, the third argument is an integer argument
- specifying the number of bytes to fill, and the fourth argument is the known
- alignment of the destination location.</p>
-
-<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
- then the caller guarantees that the destination pointer is aligned to that
- boundary.</p>
-
-<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
- <tt>llvm.memset</tt> call is a <a href="#volatile">volatile operation</a>.
- The detailed access behavior is not very cleanly specified and it is unwise
- to depend on it.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting
- at the destination location. If the argument is known to be aligned to some
- boundary, this can be specified as the fourth argument, otherwise it should
- be set to 0 or 1.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.sqrt.f32(float %Val)
- declare double @llvm.sqrt.f64(double %Val)
- declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val)
- declare fp128 @llvm.sqrt.f128(fp128 %Val)
- declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
- returning the same value as the libm '<tt>sqrt</tt>' functions would.
- Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined
- behavior for negative numbers other than -0.0 (which allows for better
- optimization, because there is no need to worry about errno being
- set). <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the sqrt of the specified operand if it is a
- nonnegative floating point number.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.powi.f32(float %Val, i32 %power)
- declare double @llvm.powi.f64(double %Val, i32 %power)
- declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power)
- declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power)
- declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
- specified (positive or negative) power. The order of evaluation of
- multiplications is not defined. When a vector of floating point type is
- used, the second argument remains a scalar integer value.</p>
-
-<h5>Arguments:</h5>
-<p>The second argument is an integer power, and the first is a value to raise to
- that power.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the first value raised to the second power with an
- unspecified sequence of rounding operations.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.sin.f32(float %Val)
- declare double @llvm.sin.f64(double %Val)
- declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val)
- declare fp128 @llvm.sin.f128(fp128 %Val)
- declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the sine of the specified operand, returning the same
- values as the libm <tt>sin</tt> functions would, and handles error conditions
- in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.cos.f32(float %Val)
- declare double @llvm.cos.f64(double %Val)
- declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val)
- declare fp128 @llvm.cos.f128(fp128 %Val)
- declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the cosine of the specified operand, returning the same
- values as the libm <tt>cos</tt> functions would, and handles error conditions
- in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.pow.f32(float %Val, float %Power)
- declare double @llvm.pow.f64(double %Val, double %Power)
- declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power)
- declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power)
- declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the
- specified (positive or negative) power.</p>
-
-<h5>Arguments:</h5>
-<p>The second argument is a floating point power, and the first is a value to
- raise to that power.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the first value raised to the second power, returning
- the same values as the libm <tt>pow</tt> functions would, and handles error
- conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.exp</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.exp.f32(float %Val)
- declare double @llvm.exp.f64(double %Val)
- declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val)
- declare fp128 @llvm.exp.f128(fp128 %Val)
- declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.exp.*</tt>' intrinsics perform the exp function.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>exp</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_exp2">'<tt>llvm.exp2.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.exp2</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.exp2.f32(float %Val)
- declare double @llvm.exp2.f64(double %Val)
- declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val)
- declare fp128 @llvm.exp2.f128(fp128 %Val)
- declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.exp2.*</tt>' intrinsics perform the exp2 function.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>exp2</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_log">'<tt>llvm.log.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.log</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.log.f32(float %Val)
- declare double @llvm.log.f64(double %Val)
- declare x86_fp80 @llvm.log.f80(x86_fp80 %Val)
- declare fp128 @llvm.log.f128(fp128 %Val)
- declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.log.*</tt>' intrinsics perform the log function.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>log</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_log10">'<tt>llvm.log10.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.log10</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.log10.f32(float %Val)
- declare double @llvm.log10.f64(double %Val)
- declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val)
- declare fp128 @llvm.log10.f128(fp128 %Val)
- declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.log10.*</tt>' intrinsics perform the log10 function.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>log10</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_log2">'<tt>llvm.log2.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.log2</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.log2.f32(float %Val)
- declare double @llvm.log2.f64(double %Val)
- declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val)
- declare fp128 @llvm.log2.f128(fp128 %Val)
- declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.log2.*</tt>' intrinsics perform the log2 function.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>log2</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.fma</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.fma.f32(float %a, float %b, float %c)
- declare double @llvm.fma.f64(double %a, double %b, double %c)
- declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
- declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
- declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.fma.*</tt>' intrinsics perform the fused multiply-add
- operation.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>fma</tt> functions
- would.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_fabs">'<tt>llvm.fabs.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.fabs</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.fabs.f32(float %Val)
- declare double @llvm.fabs.f64(double %Val)
- declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val)
- declare fp128 @llvm.fabs.f128(fp128 %Val)
- declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.fabs.*</tt>' intrinsics return the absolute value of
- the operand.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>fabs</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_floor">'<tt>llvm.floor.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.floor</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.floor.f32(float %Val)
- declare double @llvm.floor.f64(double %Val)
- declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val)
- declare fp128 @llvm.floor.f128(fp128 %Val)
- declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.floor.*</tt>' intrinsics return the floor of
- the operand.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>floor</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_ceil">'<tt>llvm.ceil.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.ceil</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.ceil.f32(float %Val)
- declare double @llvm.ceil.f64(double %Val)
- declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val)
- declare fp128 @llvm.ceil.f128(fp128 %Val)
- declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.ceil.*</tt>' intrinsics return the ceiling of
- the operand.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>ceil</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_trunc">'<tt>llvm.trunc.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.trunc</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.trunc.f32(float %Val)
- declare double @llvm.trunc.f64(double %Val)
- declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val)
- declare fp128 @llvm.trunc.f128(fp128 %Val)
- declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.trunc.*</tt>' intrinsics returns the operand rounded to the
- nearest integer not larger in magnitude than the operand.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>trunc</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_rint">'<tt>llvm.rint.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.rint</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.rint.f32(float %Val)
- declare double @llvm.rint.f64(double %Val)
- declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val)
- declare fp128 @llvm.rint.f128(fp128 %Val)
- declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.rint.*</tt>' intrinsics returns the operand rounded to the
- nearest integer. It may raise an inexact floating-point exception if the
- operand isn't an integer.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>rint</tt> functions
- would, and handles error conditions in the same way.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_nearbyint">'<tt>llvm.nearbyint.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.nearbyint</tt> on any
- floating point or vector of floating point type. Not all targets support all
- types however.</p>
-
-<pre>
- declare float @llvm.nearbyint.f32(float %Val)
- declare double @llvm.nearbyint.f64(double %Val)
- declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val)
- declare fp128 @llvm.nearbyint.f128(fp128 %Val)
- declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.nearbyint.*</tt>' intrinsics returns the operand rounded to the
- nearest integer.</p>
-
-<h5>Arguments:</h5>
-<p>The argument and return value are floating point numbers of the same
- type.</p>
-
-<h5>Semantics:</h5>
-<p>This function returns the same values as the libm <tt>nearbyint</tt>
- functions would, and handles error conditions in the same way.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_manip">Bit Manipulation Intrinsics</a>
-</h3>
-
-<div>
-
-<p>LLVM provides intrinsics for a few important bit manipulation operations.
- These allow efficient code generation for some algorithms.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic function. You can use bswap on any integer
- type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p>
-
-<pre>
- declare i16 @llvm.bswap.i16(i16 <id>)
- declare i32 @llvm.bswap.i32(i32 <id>)
- declare i64 @llvm.bswap.i64(i64 <id>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer
- values with an even number of bytes (positive multiple of 16 bits). These
- are useful for performing operations on data that is not in the target's
- native byte order.</p>
-
-<h5>Semantics:</h5>
-<p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high
- and low byte of the input i16 swapped. Similarly,
- the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four
- bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1,
- 2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order.
- The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics
- extend this concept to additional even-byte lengths (6 bytes, 8 bytes and
- more, respectively).</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
- width, or on any vector with integer elements. Not all targets support all
- bit widths or vector types, however.</p>
-
-<pre>
- declare i8 @llvm.ctpop.i8(i8 <src>)
- declare i16 @llvm.ctpop.i16(i16 <src>)
- declare i32 @llvm.ctpop.i32(i32 <src>)
- declare i64 @llvm.ctpop.i64(i64 <src>)
- declare i256 @llvm.ctpop.i256(i256 <src>)
- declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set
- in a value.</p>
-
-<h5>Arguments:</h5>
-<p>The only argument is the value to be counted. The argument may be of any
- integer type, or a vector with integer elements.
- The return type must match the argument type.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable, or within each
- element of a vector.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any
- integer bit width, or any vector whose elements are integers. Not all
- targets support all bit widths or vector types, however.</p>
-
-<pre>
- declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>)
- declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>)
- declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>)
- declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>)
- declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
- declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
- leading zeros in a variable.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is the value to be counted. This argument may be of any
- integer type, or a vectory with integer element type. The return type
- must match the first argument type.</p>
-
-<p>The second argument must be a constant and is a flag to indicate whether the
- intrinsic should ensure that a zero as the first argument produces a defined
- result. Historically some architectures did not provide a defined result for
- zero values as efficiently, and many algorithms are now predicated on
- avoiding zero-value inputs.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant)
- zeros in a variable, or within each element of the vector.
- If <tt>src == 0</tt> then the result is the size in bits of the type of
- <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise.
- For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any
- integer bit width, or any vector of integer elements. Not all targets
- support all bit widths or vector types, however.</p>
-
-<pre>
- declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>)
- declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>)
- declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>)
- declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>)
- declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
- declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
- trailing zeros.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is the value to be counted. This argument may be of any
- integer type, or a vectory with integer element type. The return type
- must match the first argument type.</p>
-
-<p>The second argument must be a constant and is a flag to indicate whether the
- intrinsic should ensure that a zero as the first argument produces a defined
- result. Historically some architectures did not provide a defined result for
- zero values as efficiently, and many algorithms are now predicated on
- avoiding zero-value inputs.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant)
- zeros in a variable, or within each element of a vector.
- If <tt>src == 0</tt> then the result is the size in bits of the type of
- <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise.
- For example, <tt>llvm.cttz(2) = 1</tt>.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_overflow">Arithmetic with Overflow Intrinsics</a>
-</h3>
-
-<div>
-
-<p>LLVM provides intrinsics for some arithmetic with overflow operations.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_sadd_overflow">
- '<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt>
- on any integer bit width.</p>
-
-<pre>
- declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
- declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
- declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
- a signed addition of the two arguments, and indicate whether an overflow
- occurred during the signed summation.</p>
-
-<h5>Arguments:</h5>
-<p>The arguments (%a and %b) and the first element of the result structure may
- be of integer types of any bit width, but they must have the same bit
- width. The second element of the result structure must be of
- type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
- undergo signed addition.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
- a signed addition of the two variables. They return a structure — the
- first element of which is the signed summation, and the second element of
- which is a bit specifying if the signed summation resulted in an
- overflow.</p>
-
-<h5>Examples:</h5>
-<pre>
- %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
- %sum = extractvalue {i32, i1} %res, 0
- %obit = extractvalue {i32, i1} %res, 1
- br i1 %obit, label %overflow, label %normal
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_uadd_overflow">
- '<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt>
- on any integer bit width.</p>
-
-<pre>
- declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
- declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
- declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
- an unsigned addition of the two arguments, and indicate whether a carry
- occurred during the unsigned summation.</p>
-
-<h5>Arguments:</h5>
-<p>The arguments (%a and %b) and the first element of the result structure may
- be of integer types of any bit width, but they must have the same bit
- width. The second element of the result structure must be of
- type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
- undergo unsigned addition.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
- an unsigned addition of the two arguments. They return a structure —
- the first element of which is the sum, and the second element of which is a
- bit specifying if the unsigned summation resulted in a carry.</p>
-
-<h5>Examples:</h5>
-<pre>
- %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
- %sum = extractvalue {i32, i1} %res, 0
- %obit = extractvalue {i32, i1} %res, 1
- br i1 %obit, label %carry, label %normal
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_ssub_overflow">
- '<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt>
- on any integer bit width.</p>
-
-<pre>
- declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
- declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
- declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
- a signed subtraction of the two arguments, and indicate whether an overflow
- occurred during the signed subtraction.</p>
-
-<h5>Arguments:</h5>
-<p>The arguments (%a and %b) and the first element of the result structure may
- be of integer types of any bit width, but they must have the same bit
- width. The second element of the result structure must be of
- type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
- undergo signed subtraction.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
- a signed subtraction of the two arguments. They return a structure —
- the first element of which is the subtraction, and the second element of
- which is a bit specifying if the signed subtraction resulted in an
- overflow.</p>
-
-<h5>Examples:</h5>
-<pre>
- %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
- %sum = extractvalue {i32, i1} %res, 0
- %obit = extractvalue {i32, i1} %res, 1
- br i1 %obit, label %overflow, label %normal
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_usub_overflow">
- '<tt>llvm.usub.with.overflow.*</tt>' Intrinsics
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt>
- on any integer bit width.</p>
-
-<pre>
- declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
- declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
- declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
- an unsigned subtraction of the two arguments, and indicate whether an
- overflow occurred during the unsigned subtraction.</p>
-
-<h5>Arguments:</h5>
-<p>The arguments (%a and %b) and the first element of the result structure may
- be of integer types of any bit width, but they must have the same bit
- width. The second element of the result structure must be of
- type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
- undergo unsigned subtraction.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
- an unsigned subtraction of the two arguments. They return a structure —
- the first element of which is the subtraction, and the second element of
- which is a bit specifying if the unsigned subtraction resulted in an
- overflow.</p>
-
-<h5>Examples:</h5>
-<pre>
- %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
- %sum = extractvalue {i32, i1} %res, 0
- %obit = extractvalue {i32, i1} %res, 1
- br i1 %obit, label %overflow, label %normal
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_smul_overflow">
- '<tt>llvm.smul.with.overflow.*</tt>' Intrinsics
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt>
- on any integer bit width.</p>
-
-<pre>
- declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
- declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
- declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
-</pre>
-
-<h5>Overview:</h5>
-
-<p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
- a signed multiplication of the two arguments, and indicate whether an
- overflow occurred during the signed multiplication.</p>
-
-<h5>Arguments:</h5>
-<p>The arguments (%a and %b) and the first element of the result structure may
- be of integer types of any bit width, but they must have the same bit
- width. The second element of the result structure must be of
- type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
- undergo signed multiplication.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
- a signed multiplication of the two arguments. They return a structure —
- the first element of which is the multiplication, and the second element of
- which is a bit specifying if the signed multiplication resulted in an
- overflow.</p>
-
-<h5>Examples:</h5>
-<pre>
- %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
- %sum = extractvalue {i32, i1} %res, 0
- %obit = extractvalue {i32, i1} %res, 1
- br i1 %obit, label %overflow, label %normal
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_umul_overflow">
- '<tt>llvm.umul.with.overflow.*</tt>' Intrinsics
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt>
- on any integer bit width.</p>
-
-<pre>
- declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
- declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
- declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
- a unsigned multiplication of the two arguments, and indicate whether an
- overflow occurred during the unsigned multiplication.</p>
-
-<h5>Arguments:</h5>
-<p>The arguments (%a and %b) and the first element of the result structure may
- be of integer types of any bit width, but they must have the same bit
- width. The second element of the result structure must be of
- type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
- undergo unsigned multiplication.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
- an unsigned multiplication of the two arguments. They return a structure
- — the first element of which is the multiplication, and the second
- element of which is a bit specifying if the unsigned multiplication resulted
- in an overflow.</p>
-
-<h5>Examples:</h5>
-<pre>
- %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
- %sum = extractvalue {i32, i1} %res, 0
- %obit = extractvalue {i32, i1} %res, 1
- br i1 %obit, label %overflow, label %normal
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="spec_arithmetic">Specialised Arithmetic Intrinsics</a>
-</h3>
-
-<!-- _______________________________________________________________________ -->
-
-<h4>
- <a name="fmuladd">'<tt>llvm.fmuladd.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
- declare double @llvm.fmuladd.f64(double %a, double %b, double %c)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.fmuladd.*</tt>' intrinsic functions represent multiply-add
-expressions that can be fused if the code generator determines that the fused
-expression would be legal and efficient.</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>llvm.fmuladd.*</tt>' intrinsics each take three arguments: two
-multiplicands, a and b, and an addend c.</p>
-
-<h5>Semantics:</h5>
-<p>The expression:</p>
-<pre>
- %0 = call float @llvm.fmuladd.f32(%a, %b, %c)
-</pre>
-<p>is equivalent to the expression a * b + c, except that rounding will not be
-performed between the multiplication and addition steps if the code generator
-fuses the operations. Fusion is not guaranteed, even if the target platform
-supports it. If a fused multiply-add is required the corresponding llvm.fma.*
-intrinsic function should be used instead.</p>
-
-<h5>Examples:</h5>
-<pre>
- %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields {float}:r2 = (a * b) + c
-</pre>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_fp16">Half Precision Floating Point Intrinsics</a>
-</h3>
-
-<div>
-
-<p>For most target platforms, half precision floating point is a storage-only
- format. This means that it is
- a dense encoding (in memory) but does not support computation in the
- format.</p>
-
-<p>This means that code must first load the half-precision floating point
- value as an i16, then convert it to float with <a
- href="#int_convert_from_fp16"><tt>llvm.convert.from.fp16</tt></a>.
- Computation can then be performed on the float value (including extending to
- double etc). To store the value back to memory, it is first converted to
- float if needed, then converted to i16 with
- <a href="#int_convert_to_fp16"><tt>llvm.convert.to.fp16</tt></a>, then
- storing as an i16 value.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_convert_to_fp16">
- '<tt>llvm.convert.to.fp16</tt>' Intrinsic
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i16 @llvm.convert.to.fp16(f32 %a)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
- a conversion from single precision floating point format to half precision
- floating point format.</p>
-
-<h5>Arguments:</h5>
-<p>The intrinsic function contains single argument - the value to be
- converted.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
- a conversion from single precision floating point format to half precision
- floating point format. The return value is an <tt>i16</tt> which
- contains the converted number.</p>
-
-<h5>Examples:</h5>
-<pre>
- %res = call i16 @llvm.convert.to.fp16(f32 %a)
- store i16 %res, i16* @x, align 2
-</pre>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_convert_from_fp16">
- '<tt>llvm.convert.from.fp16</tt>' Intrinsic
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare f32 @llvm.convert.from.fp16(i16 %a)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs
- a conversion from half precision floating point format to single precision
- floating point format.</p>
-
-<h5>Arguments:</h5>
-<p>The intrinsic function contains single argument - the value to be
- converted.</p>
-
-<h5>Semantics:</h5>
-<p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs a
- conversion from half single precision floating point format to single
- precision floating point format. The input half-float value is represented by
- an <tt>i16</tt> value.</p>
-
-<h5>Examples:</h5>
-<pre>
- %a = load i16* @x, align 2
- %res = call f32 @llvm.convert.from.fp16(i16 %a)
-</pre>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_debugger">Debugger Intrinsics</a>
-</h3>
-
-<div>
-
-<p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt>
- prefix), are described in
- the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source
- Level Debugging</a> document.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_eh">Exception Handling Intrinsics</a>
-</h3>
-
-<div>
-
-<p>The LLVM exception handling intrinsics (which all start with
- <tt>llvm.eh.</tt> prefix), are described in
- the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception
- Handling</a> document.</p>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_trampoline">Trampoline Intrinsics</a>
-</h3>
-
-<div>
-
-<p>These intrinsics make it possible to excise one parameter, marked with
- the <a href="#nest"><tt>nest</tt></a> attribute, from a function.
- The result is a callable
- function pointer lacking the nest parameter - the caller does not need to
- provide a value for it. Instead, the value to use is stored in advance in a
- "trampoline", a block of memory usually allocated on the stack, which also
- contains code to splice the nest value into the argument list. This is used
- to implement the GCC nested function address extension.</p>
-
-<p>For example, if the function is
- <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function
- pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as
- follows:</p>
-
-<pre class="doc_code">
- %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
- %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
- call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
- %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
- %fp = bitcast i8* %p to i32 (i32, i32)*
-</pre>
-
-<p>The call <tt>%val = call i32 %fp(i32 %x, i32 %y)</tt> is then equivalent
- to <tt>%val = call i32 %f(i8* %nval, i32 %x, i32 %y)</tt>.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_it">
- '<tt>llvm.init.trampoline</tt>' Intrinsic
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
-</pre>
-
-<h5>Overview:</h5>
-<p>This fills the memory pointed to by <tt>tramp</tt> with executable code,
- turning it into a trampoline.</p>
-
-<h5>Arguments:</h5>
-<p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all
- pointers. The <tt>tramp</tt> argument must point to a sufficiently large and
- sufficiently aligned block of memory; this memory is written to by the
- intrinsic. Note that the size and the alignment are target-specific - LLVM
- currently provides no portable way of determining them, so a front-end that
- generates this intrinsic needs to have some target-specific knowledge.
- The <tt>func</tt> argument must hold a function bitcast to
- an <tt>i8*</tt>.</p>
-
-<h5>Semantics:</h5>
-<p>The block of memory pointed to by <tt>tramp</tt> is filled with target
- dependent code, turning it into a function. Then <tt>tramp</tt> needs to be
- passed to <a href="#int_at">llvm.adjust.trampoline</a> to get a pointer
- which can be <a href="#int_trampoline">bitcast (to a new function) and
- called</a>. The new function's signature is the same as that of
- <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute
- removed. At most one such <tt>nest</tt> argument is allowed, and it must be of
- pointer type. Calling the new function is equivalent to calling <tt>func</tt>
- with the same argument list, but with <tt>nval</tt> used for the missing
- <tt>nest</tt> argument. If, after calling <tt>llvm.init.trampoline</tt>, the
- memory pointed to by <tt>tramp</tt> is modified, then the effect of any later call
- to the returned function pointer is undefined.</p>
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_at">
- '<tt>llvm.adjust.trampoline</tt>' Intrinsic
- </a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i8* @llvm.adjust.trampoline(i8* <tramp>)
-</pre>
-
-<h5>Overview:</h5>
-<p>This performs any required machine-specific adjustment to the address of a
- trampoline (passed as <tt>tramp</tt>).</p>
-
-<h5>Arguments:</h5>
-<p><tt>tramp</tt> must point to a block of memory which already has trampoline code
- filled in by a previous call to <a href="#int_it"><tt>llvm.init.trampoline</tt>
- </a>.</p>
-
-<h5>Semantics:</h5>
-<p>On some architectures the address of the code to be executed needs to be
- different to the address where the trampoline is actually stored. This
- intrinsic returns the executable address corresponding to <tt>tramp</tt>
- after performing the required machine specific adjustments.
- The pointer returned can then be <a href="#int_trampoline"> bitcast and
- executed</a>.
-</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_memorymarkers">Memory Use Markers</a>
-</h3>
-
-<div>
-
-<p>This class of intrinsics exists to information about the lifetime of memory
- objects and ranges where variables are immutable.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory
- object's lifetime.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is a constant integer representing the size of the
- object, or -1 if it is variable sized. The second argument is a pointer to
- the object.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic indicates that before this point in the code, the value of the
- memory pointed to by <tt>ptr</tt> is dead. This means that it is known to
- never be used and has an undefined value. A load from the pointer that
- precedes this intrinsic can be replaced with
- <tt>'<a href="#undefvalues">undef</a>'</tt>.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory
- object's lifetime.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is a constant integer representing the size of the
- object, or -1 if it is variable sized. The second argument is a pointer to
- the object.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic indicates that after this point in the code, the value of the
- memory pointed to by <tt>ptr</tt> is dead. This means that it is known to
- never be used and has an undefined value. Any stores into the memory object
- following this intrinsic may be removed as dead.
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of
- a memory object will not change.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is a constant integer representing the size of the
- object, or -1 if it is variable sized. The second argument is a pointer to
- the object.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses
- the return value, the referenced memory location is constant and
- unchanging.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of
- a memory object are mutable.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic.
- The second argument is a constant integer representing the size of the
- object, or -1 if it is variable sized and the third argument is a pointer
- to the object.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic indicates that the memory is mutable again.</p>
-
-</div>
-
-</div>
-
-<!-- ======================================================================= -->
-<h3>
- <a name="int_general">General Intrinsics</a>
-</h3>
-
-<div>
-
-<p>This class of intrinsics is designed to be generic and has no specific
- purpose.</p>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_var_annotation">'<tt>llvm.var.annotation</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is a pointer to a value, the second is a pointer to a
- global string, the third is a pointer to a global string which is the source
- file name, and the last argument is the line number.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic allows annotation of local variables with arbitrary strings.
- This can be useful for special purpose optimizations that want to look for
- these annotations. These have no other defined use; they are ignored by code
- generation and optimization.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_annotation">'<tt>llvm.annotation.*</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on
- any integer bit width.</p>
-
-<pre>
- declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>)
- declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>)
- declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>)
- declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>)
- declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.annotation</tt>' intrinsic.</p>
-
-<h5>Arguments:</h5>
-<p>The first argument is an integer value (result of some expression), the
- second is a pointer to a global string, the third is a pointer to a global
- string which is the source file name, and the last argument is the line
- number. It returns the value of the first argument.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic allows annotations to be put on arbitrary expressions with
- arbitrary strings. This can be useful for special purpose optimizations that
- want to look for these annotations. These have no other defined use; they
- are ignored by code generation and optimization.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_trap">'<tt>llvm.trap</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.trap() noreturn nounwind
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.trap</tt>' intrinsic.</p>
-
-<h5>Arguments:</h5>
-<p>None.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic is lowered to the target dependent trap instruction. If the
- target does not have a trap instruction, this intrinsic will be lowered to
- a call of the <tt>abort()</tt> function.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_debugtrap">'<tt>llvm.debugtrap</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.debugtrap() nounwind
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>llvm.debugtrap</tt>' intrinsic.</p>
-
-<h5>Arguments:</h5>
-<p>None.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic is lowered to code which is intended to cause an execution
- trap with the intention of requesting the attention of a debugger.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and
- stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to
- ensure that it is placed on the stack before local variables.</p>
-
-<h5>Arguments:</h5>
-<p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer
- arguments. The first argument is the value loaded from the stack
- guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt>
- that has enough space to hold the value of the guard.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic causes the prologue/epilogue inserter to force the position of
- the <tt>AllocaInst</tt> stack slot to be before local variables on the
- stack. This is to ensure that if a local variable on the stack is
- overwritten, it will destroy the value of the guard. When the function exits,
- the guard on the stack is checked against the original guard. If they are
- different, then the program aborts by calling the <tt>__stack_chk_fail()</tt>
- function.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>)
- declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information to
- the optimizers to determine at compile time whether a) an operation (like
- memcpy) will overflow a buffer that corresponds to an object, or b) that a
- runtime check for overflow isn't necessary. An object in this context means
- an allocation of a specific class, structure, array, or other object.</p>
-
-<h5>Arguments:</h5>
-<p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments. The first
- argument is a pointer to or into the <tt>object</tt>. The second argument
- is a boolean and determines whether <tt>llvm.objectsize</tt> returns 0 (if
- true) or -1 (if false) when the object size is unknown.
- The second argument only accepts constants.</p>
-
-<h5>Semantics:</h5>
-<p>The <tt>llvm.objectsize</tt> intrinsic is lowered to a constant representing
- the size of the object concerned. If the size cannot be determined at compile
- time, <tt>llvm.objectsize</tt> returns <tt>i32/i64 -1 or 0</tt>
- (depending on the <tt>min</tt> argument).</p>
-
-</div>
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_expect">'<tt>llvm.expect</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
- declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)
-</pre>
-
-<h5>Overview:</h5>
-<p>The <tt>llvm.expect</tt> intrinsic provides information about expected (the
- most probable) value of <tt>val</tt>, which can be used by optimizers.</p>
-
-<h5>Arguments:</h5>
-<p>The <tt>llvm.expect</tt> intrinsic takes two arguments. The first
- argument is a value. The second argument is an expected value, this needs to
- be a constant value, variables are not allowed.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic is lowered to the <tt>val</tt>.</p>
-</div>
-
-<!-- _______________________________________________________________________ -->
-<h4>
- <a name="int_donothing">'<tt>llvm.donothing</tt>' Intrinsic</a>
-</h4>
-
-<div>
-
-<h5>Syntax:</h5>
-<pre>
- declare void @llvm.donothing() nounwind readnone
-</pre>
-
-<h5>Overview:</h5>
-<p>The <tt>llvm.donothing</tt> intrinsic doesn't perform any operation. It's the
-only intrinsic that can be called with an invoke instruction.</p>
-
-<h5>Arguments:</h5>
-<p>None.</p>
-
-<h5>Semantics:</h5>
-<p>This intrinsic does nothing, and it's removed by optimizers and ignored by
-codegen.</p>
-</div>
-
-</div>
-
-</div>
-<!-- *********************************************************************** -->
-<hr>
-<address>
- <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
- <a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
-
- <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
- <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
- Last modified: $Date$
-</address>
-
-</body>
-</html>
--- /dev/null
+==============================
+LLVM Language Reference Manual
+==============================
+
+.. contents::
+ :local:
+ :depth: 3
+
+Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Vikram
+Adve <mailto:vadve@cs.uiuc.edu>`_
+
+Abstract
+========
+
+This document is a reference manual for the LLVM assembly language. LLVM
+is a Static Single Assignment (SSA) based representation that provides
+type safety, low-level operations, flexibility, and the capability of
+representing 'all' high-level languages cleanly. It is the common code
+representation used throughout all phases of the LLVM compilation
+strategy.
+
+Introduction
+============
+
+The LLVM code representation is designed to be used in three different
+forms: as an in-memory compiler IR, as an on-disk bitcode representation
+(suitable for fast loading by a Just-In-Time compiler), and as a human
+readable assembly language representation. This allows LLVM to provide a
+powerful intermediate representation for efficient compiler
+transformations and analysis, while providing a natural means to debug
+and visualize the transformations. The three different forms of LLVM are
+all equivalent. This document describes the human readable
+representation and notation.
+
+The LLVM representation aims to be light-weight and low-level while
+being expressive, typed, and extensible at the same time. It aims to be
+a "universal IR" of sorts, by being at a low enough level that
+high-level ideas may be cleanly mapped to it (similar to how
+microprocessors are "universal IR's", allowing many source languages to
+be mapped to them). By providing type information, LLVM can be used as
+the target of optimizations: for example, through pointer analysis, it
+can be proven that a C automatic variable is never accessed outside of
+the current function, allowing it to be promoted to a simple SSA value
+instead of a memory location.
+
+.. _wellformed:
+
+Well-Formedness
+---------------
+
+It is important to note that this document describes 'well formed' LLVM
+assembly language. There is a difference between what the parser accepts
+and what is considered 'well formed'. For example, the following
+instruction is syntactically okay, but not well formed:
+
+.. code-block:: llvm
+
+ %x = add i32 1, %x
+
+because the definition of ``%x`` does not dominate all of its uses. The
+LLVM infrastructure provides a verification pass that may be used to
+verify that an LLVM module is well formed. This pass is automatically
+run by the parser after parsing input assembly and by the optimizer
+before it outputs bitcode. The violations pointed out by the verifier
+pass indicate bugs in transformation passes or input to the parser.
+
+.. _identifiers:
+
+Identifiers
+===========
+
+LLVM identifiers come in two basic types: global and local. Global
+identifiers (functions, global variables) begin with the ``'@'``
+character. Local identifiers (register names, types) begin with the
+``'%'`` character. Additionally, there are three different formats for
+identifiers, for different purposes:
+
+#. Named values are represented as a string of characters with their
+ prefix. For example, ``%foo``, ``@DivisionByZero``,
+ ``%a.really.long.identifier``. The actual regular expression used is
+ '``[%@][a-zA-Z$._][a-zA-Z$._0-9]*``'. Identifiers which require other
+ characters in their names can be surrounded with quotes. Special
+ characters may be escaped using ``"\xx"`` where ``xx`` is the ASCII
+ code for the character in hexadecimal. In this way, any character can
+ be used in a name value, even quotes themselves.
+#. Unnamed values are represented as an unsigned numeric value with
+ their prefix. For example, ``%12``, ``@2``, ``%44``.
+#. Constants, which are described in the section Constants_ below.
+
+LLVM requires that values start with a prefix for two reasons: Compilers
+don't need to worry about name clashes with reserved words, and the set
+of reserved words may be expanded in the future without penalty.
+Additionally, unnamed identifiers allow a compiler to quickly come up
+with a temporary variable without having to avoid symbol table
+conflicts.
+
+Reserved words in LLVM are very similar to reserved words in other
+languages. There are keywords for different opcodes ('``add``',
+'``bitcast``', '``ret``', etc...), for primitive type names ('``void``',
+'``i32``', etc...), and others. These reserved words cannot conflict
+with variable names, because none of them start with a prefix character
+(``'%'`` or ``'@'``).
+
+Here is an example of LLVM code to multiply the integer variable
+'``%X``' by 8:
+
+The easy way:
+
+.. code-block:: llvm
+
+ %result = mul i32 %X, 8
+
+After strength reduction:
+
+.. code-block:: llvm
+
+ %result = shl i32 %X, i8 3
+
+And the hard way:
+
+.. code-block:: llvm
+
+ %0 = add i32 %X, %X ; yields {i32}:%0
+ %1 = add i32 %0, %0 ; yields {i32}:%1
+ %result = add i32 %1, %1
+
+This last way of multiplying ``%X`` by 8 illustrates several important
+lexical features of LLVM:
+
+#. Comments are delimited with a '``;``' and go until the end of line.
+#. Unnamed temporaries are created when the result of a computation is
+ not assigned to a named value.
+#. Unnamed temporaries are numbered sequentially
+
+It also shows a convention that we follow in this document. When
+demonstrating instructions, we will follow an instruction with a comment
+that defines the type and name of value produced.
+
+High Level Structure
+====================
+
+Module Structure
+----------------
+
+LLVM programs are composed of ``Module``'s, each of which is a
+translation unit of the input programs. Each module consists of
+functions, global variables, and symbol table entries. Modules may be
+combined together with the LLVM linker, which merges function (and
+global variable) definitions, resolves forward declarations, and merges
+symbol table entries. Here is an example of the "hello world" module:
+
+.. code-block:: llvm
+
+ ; Declare the string constant as a global constant.
+ @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
+
+ ; External declaration of the puts function
+ declare i32 @puts(i8* nocapture) nounwind
+
+ ; Definition of main function
+ define i32 @main() { ; i32()*
+ ; Convert [13 x i8]* to i8 *...
+ %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0
+
+ ; Call puts function to write out the string to stdout.
+ call i32 @puts(i8* %cast210)
+ ret i32 0
+ }
+
+ ; Named metadata
+ !1 = metadata !{i32 42}
+ !foo = !{!1, null}
+
+This example is made up of a :ref:`global variable <globalvars>` named
+"``.str``", an external declaration of the "``puts``" function, a
+:ref:`function definition <functionstructure>` for "``main``" and
+:ref:`named metadata <namedmetadatastructure>` "``foo``".
+
+In general, a module is made up of a list of global values (where both
+functions and global variables are global values). Global values are
+represented by a pointer to a memory location (in this case, a pointer
+to an array of char, and a pointer to a function), and have one of the
+following :ref:`linkage types <linkage>`.
+
+.. _linkage:
+
+Linkage Types
+-------------
+
+All Global Variables and Functions have one of the following types of
+linkage:
+
+``private``
+ Global values with "``private``" linkage are only directly
+ accessible by objects in the current module. In particular, linking
+ code into a module with an private global value may cause the
+ private to be renamed as necessary to avoid collisions. Because the
+ symbol is private to the module, all references can be updated. This
+ doesn't show up in any symbol table in the object file.
+``linker_private``
+ Similar to ``private``, but the symbol is passed through the
+ assembler and evaluated by the linker. Unlike normal strong symbols,
+ they are removed by the linker from the final linked image
+ (executable or dynamic library).
+``linker_private_weak``
+ Similar to "``linker_private``", but the symbol is weak. Note that
+ ``linker_private_weak`` symbols are subject to coalescing by the
+ linker. The symbols are removed by the linker from the final linked
+ image (executable or dynamic library).
+``internal``
+ Similar to private, but the value shows as a local symbol
+ (``STB_LOCAL`` in the case of ELF) in the object file. This
+ corresponds to the notion of the '``static``' keyword in C.
+``available_externally``
+ Globals with "``available_externally``" linkage are never emitted
+ into the object file corresponding to the LLVM module. They exist to
+ allow inlining and other optimizations to take place given knowledge
+ of the definition of the global, which is known to be somewhere
+ outside the module. Globals with ``available_externally`` linkage
+ are allowed to be discarded at will, and are otherwise the same as
+ ``linkonce_odr``. This linkage type is only allowed on definitions,
+ not declarations.
+``linkonce``
+ Globals with "``linkonce``" linkage are merged with other globals of
+ the same name when linkage occurs. This can be used to implement
+ some forms of inline functions, templates, or other code which must
+ be generated in each translation unit that uses it, but where the
+ body may be overridden with a more definitive definition later.
+ Unreferenced ``linkonce`` globals are allowed to be discarded. Note
+ that ``linkonce`` linkage does not actually allow the optimizer to
+ inline the body of this function into callers because it doesn't
+ know if this definition of the function is the definitive definition
+ within the program or whether it will be overridden by a stronger
+ definition. To enable inlining and other optimizations, use
+ "``linkonce_odr``" linkage.
+``weak``
+ "``weak``" linkage has the same merging semantics as ``linkonce``
+ linkage, except that unreferenced globals with ``weak`` linkage may
+ not be discarded. This is used for globals that are declared "weak"
+ in C source code.
+``common``
+ "``common``" linkage is most similar to "``weak``" linkage, but they
+ are used for tentative definitions in C, such as "``int X;``" at
+ global scope. Symbols with "``common``" linkage are merged in the
+ same way as ``weak symbols``, and they may not be deleted if
+ unreferenced. ``common`` symbols may not have an explicit section,
+ must have a zero initializer, and may not be marked
+ ':ref:`constant <globalvars>`'. Functions and aliases may not have
+ common linkage.
+
+.. _linkage_appending:
+
+``appending``
+ "``appending``" linkage may only be applied to global variables of
+ pointer to array type. When two global variables with appending
+ linkage are linked together, the two global arrays are appended
+ together. This is the LLVM, typesafe, equivalent of having the
+ system linker append together "sections" with identical names when
+ .o files are linked.
+``extern_weak``
+ The semantics of this linkage follow the ELF object file model: the
+ symbol is weak until linked, if not linked, the symbol becomes null
+ instead of being an undefined reference.
+``linkonce_odr``, ``weak_odr``
+ Some languages allow differing globals to be merged, such as two
+ functions with different semantics. Other languages, such as
+ ``C++``, ensure that only equivalent globals are ever merged (the
+ "one definition rule" — "ODR"). Such languages can use the
+ ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
+ global will only be merged with equivalent globals. These linkage
+ types are otherwise the same as their non-``odr`` versions.
+``linkonce_odr_auto_hide``
+ Similar to "``linkonce_odr``", but nothing in the translation unit
+ takes the address of this definition. For instance, functions that
+ had an inline definition, but the compiler decided not to inline it.
+ ``linkonce_odr_auto_hide`` may have only ``default`` visibility. The
+ symbols are removed by the linker from the final linked image
+ (executable or dynamic library).
+``external``
+ If none of the above identifiers are used, the global is externally
+ visible, meaning that it participates in linkage and can be used to
+ resolve external symbol references.
+
+The next two types of linkage are targeted for Microsoft Windows
+platform only. They are designed to support importing (exporting)
+symbols from (to) DLLs (Dynamic Link Libraries).
+
+``dllimport``
+ "``dllimport``" linkage causes the compiler to reference a function
+ or variable via a global pointer to a pointer that is set up by the
+ DLL exporting the symbol. On Microsoft Windows targets, the pointer
+ name is formed by combining ``__imp_`` and the function or variable
+ name.
+``dllexport``
+ "``dllexport``" linkage causes the compiler to provide a global
+ pointer to a pointer in a DLL, so that it can be referenced with the
+ ``dllimport`` attribute. On Microsoft Windows targets, the pointer
+ name is formed by combining ``__imp_`` and the function or variable
+ name.
+
+For example, since the "``.LC0``" variable is defined to be internal, if
+another module defined a "``.LC0``" variable and was linked with this
+one, one of the two would be renamed, preventing a collision. Since
+"``main``" and "``puts``" are external (i.e., lacking any linkage
+declarations), they are accessible outside of the current module.
+
+It is illegal for a function *declaration* to have any linkage type
+other than ``external``, ``dllimport`` or ``extern_weak``.
+
+Aliases can have only ``external``, ``internal``, ``weak`` or
+``weak_odr`` linkages.
+
+.. _callingconv:
+
+Calling Conventions
+-------------------
+
+LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and
+:ref:`invokes <i_invoke>` can all have an optional calling convention
+specified for the call. The calling convention of any pair of dynamic
+caller/callee must match, or the behavior of the program is undefined.
+The following calling conventions are supported by LLVM, and more may be
+added in the future:
+
+"``ccc``" - The C calling convention
+ This calling convention (the default if no other calling convention
+ is specified) matches the target C calling conventions. This calling
+ convention supports varargs function calls and tolerates some
+ mismatch in the declared prototype and implemented declaration of
+ the function (as does normal C).
+"``fastcc``" - The fast calling convention
+ This calling convention attempts to make calls as fast as possible
+ (e.g. by passing things in registers). This calling convention
+ allows the target to use whatever tricks it wants to produce fast
+ code for the target, without having to conform to an externally
+ specified ABI (Application Binary Interface). `Tail calls can only
+ be optimized when this, the GHC or the HiPE convention is
+ used. <CodeGenerator.html#id80>`_ This calling convention does not
+ support varargs and requires the prototype of all callees to exactly
+ match the prototype of the function definition.
+"``coldcc``" - The cold calling convention
+ This calling convention attempts to make code in the caller as
+ efficient as possible under the assumption that the call is not
+ commonly executed. As such, these calls often preserve all registers
+ so that the call does not break any live ranges in the caller side.
+ This calling convention does not support varargs and requires the
+ prototype of all callees to exactly match the prototype of the
+ function definition.
+"``cc 10``" - GHC convention
+ This calling convention has been implemented specifically for use by
+ the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_.
+ It passes everything in registers, going to extremes to achieve this
+ by disabling callee save registers. This calling convention should
+ not be used lightly but only for specific situations such as an
+ alternative to the *register pinning* performance technique often
+ used when implementing functional programming languages. At the
+ moment only X86 supports this convention and it has the following
+ limitations:
+
+ - On *X86-32* only supports up to 4 bit type parameters. No
+ floating point types are supported.
+ - On *X86-64* only supports up to 10 bit type parameters and 6
+ floating point parameters.
+
+ This calling convention supports `tail call
+ optimization <CodeGenerator.html#id80>`_ but requires both the
+ caller and callee are using it.
+"``cc 11``" - The HiPE calling convention
+ This calling convention has been implemented specifically for use by
+ the `High-Performance Erlang
+ (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the*
+ native code compiler of the `Ericsson's Open Source Erlang/OTP
+ system <http://www.erlang.org/download.shtml>`_. It uses more
+ registers for argument passing than the ordinary C calling
+ convention and defines no callee-saved registers. The calling
+ convention properly supports `tail call
+ optimization <CodeGenerator.html#id80>`_ but requires that both the
+ caller and the callee use it. It uses a *register pinning*
+ mechanism, similar to GHC's convention, for keeping frequently
+ accessed runtime components pinned to specific hardware registers.
+ At the moment only X86 supports this convention (both 32 and 64
+ bit).
+"``cc <n>``" - Numbered convention
+ Any calling convention may be specified by number, allowing
+ target-specific calling conventions to be used. Target specific
+ calling conventions start at 64.
+
+More calling conventions can be added/defined on an as-needed basis, to
+support Pascal conventions or any other well-known target-independent
+convention.
+
+Visibility Styles
+-----------------
+
+All Global Variables and Functions have one of the following visibility
+styles:
+
+"``default``" - Default style
+ On targets that use the ELF object file format, default visibility
+ means that the declaration is visible to other modules and, in
+ shared libraries, means that the declared entity may be overridden.
+ On Darwin, default visibility means that the declaration is visible
+ to other modules. Default visibility corresponds to "external
+ linkage" in the language.
+"``hidden``" - Hidden style
+ Two declarations of an object with hidden visibility refer to the
+ same object if they are in the same shared object. Usually, hidden
+ visibility indicates that the symbol will not be placed into the
+ dynamic symbol table, so no other module (executable or shared
+ library) can reference it directly.
+"``protected``" - Protected style
+ On ELF, protected visibility indicates that the symbol will be
+ placed in the dynamic symbol table, but that references within the
+ defining module will bind to the local symbol. That is, the symbol
+ cannot be overridden by another module.
+
+Named Types
+-----------
+
+LLVM IR allows you to specify name aliases for certain types. This can
+make it easier to read the IR and make the IR more condensed
+(particularly when recursive types are involved). An example of a name
+specification is:
+
+.. code-block:: llvm
+
+ %mytype = type { %mytype*, i32 }
+
+You may give a name to any :ref:`type <typesystem>` except
+":ref:`void <t_void>`". Type name aliases may be used anywhere a type is
+expected with the syntax "%mytype".
+
+Note that type names are aliases for the structural type that they
+indicate, and that you can therefore specify multiple names for the same
+type. This often leads to confusing behavior when dumping out a .ll
+file. Since LLVM IR uses structural typing, the name is not part of the
+type. When printing out LLVM IR, the printer will pick *one name* to
+render all types of a particular shape. This means that if you have code
+where two different source types end up having the same LLVM type, that
+the dumper will sometimes print the "wrong" or unexpected type. This is
+an important design point and isn't going to change.
+
+.. _globalvars:
+
+Global Variables
+----------------
+
+Global variables define regions of memory allocated at compilation time
+instead of run-time. Global variables may optionally be initialized, may
+have an explicit section to be placed in, and may have an optional
+explicit alignment specified.
+
+A variable may be defined as ``thread_local``, which means that it will
+not be shared by threads (each thread will have a separated copy of the
+variable). Not all targets support thread-local variables. Optionally, a
+TLS model may be specified:
+
+``localdynamic``
+ For variables that are only used within the current shared library.
+``initialexec``
+ For variables in modules that will not be loaded dynamically.
+``localexec``
+ For variables defined in the executable and only used within it.
+
+The models correspond to the ELF TLS models; see `ELF Handling For
+Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for
+more information on under which circumstances the different models may
+be used. The target may choose a different TLS model if the specified
+model is not supported, or if a better choice of model can be made.
+
+A variable may be defined as a global "constant," which indicates that
+the contents of the variable will **never** be modified (enabling better
+optimization, allowing the global data to be placed in the read-only
+section of an executable, etc). Note that variables that need runtime
+initialization cannot be marked "constant" as there is a store to the
+variable.
+
+LLVM explicitly allows *declarations* of global variables to be marked
+constant, even if the final definition of the global is not. This
+capability can be used to enable slightly better optimization of the
+program, but requires the language definition to guarantee that
+optimizations based on the 'constantness' are valid for the translation
+units that do not include the definition.
+
+As SSA values, global variables define pointer values that are in scope
+(i.e. they dominate) all basic blocks in the program. Global variables
+always define a pointer to their "content" type because they describe a
+region of memory, and all memory objects in LLVM are accessed through
+pointers.
+
+Global variables can be marked with ``unnamed_addr`` which indicates
+that the address is not significant, only the content. Constants marked
+like this can be merged with other constants if they have the same
+initializer. Note that a constant with significant address *can* be
+merged with a ``unnamed_addr`` constant, the result being a constant
+whose address is significant.
+
+A global variable may be declared to reside in a target-specific
+numbered address space. For targets that support them, address spaces
+may affect how optimizations are performed and/or what target
+instructions are used to access the variable. The default address space
+is zero. The address space qualifier must precede any other attributes.
+
+LLVM allows an explicit section to be specified for globals. If the
+target supports it, it will emit globals to the section specified.
+
+An explicit alignment may be specified for a global, which must be a
+power of 2. If not present, or if the alignment is set to zero, the
+alignment of the global is set by the target to whatever it feels
+convenient. If an explicit alignment is specified, the global is forced
+to have exactly that alignment. Targets and optimizers are not allowed
+to over-align the global if the global has an assigned section. In this
+case, the extra alignment could be observable: for example, code could
+assume that the globals are densely packed in their section and try to
+iterate over them as an array, alignment padding would break this
+iteration.
+
+For example, the following defines a global in a numbered address space
+with an initializer, section, and alignment:
+
+.. code-block:: llvm
+
+ @G = addrspace(5) constant float 1.0, section "foo", align 4
+
+The following example defines a thread-local global with the
+``initialexec`` TLS model:
+
+.. code-block:: llvm
+
+ @G = thread_local(initialexec) global i32 0, align 4
+
+.. _functionstructure:
+
+Functions
+---------
+
+LLVM function definitions consist of the "``define``" keyword, an
+optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
+style <visibility>`, an optional :ref:`calling convention <callingconv>`,
+an optional ``unnamed_addr`` attribute, a return type, an optional
+:ref:`parameter attribute <paramattrs>` for the return type, a function
+name, a (possibly empty) argument list (each with optional :ref:`parameter
+attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`,
+an optional section, an optional alignment, an optional :ref:`garbage
+collector name <gc>`, an opening curly brace, a list of basic blocks,
+and a closing curly brace.
+
+LLVM function declarations consist of the "``declare``" keyword, an
+optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
+style <visibility>`, an optional :ref:`calling convention <callingconv>`,
+an optional ``unnamed_addr`` attribute, a return type, an optional
+:ref:`parameter attribute <paramattrs>` for the return type, a function
+name, a possibly empty list of arguments, an optional alignment, and an
+optional :ref:`garbage collector name <gc>`.
+
+A function definition contains a list of basic blocks, forming the CFG
+(Control Flow Graph) for the function. Each basic block may optionally
+start with a label (giving the basic block a symbol table entry),
+contains a list of instructions, and ends with a
+:ref:`terminator <terminators>` instruction (such as a branch or function
+return).
+
+The first basic block in a function is special in two ways: it is
+immediately executed on entrance to the function, and it is not allowed
+to have predecessor basic blocks (i.e. there can not be any branches to
+the entry block of a function). Because the block can have no
+predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`.
+
+LLVM allows an explicit section to be specified for functions. If the
+target supports it, it will emit functions to the section specified.
+
+An explicit alignment may be specified for a function. If not present,
+or if the alignment is set to zero, the alignment of the function is set
+by the target to whatever it feels convenient. If an explicit alignment
+is specified, the function is forced to have at least that much
+alignment. All alignments must be a power of 2.
+
+If the ``unnamed_addr`` attribute is given, the address is know to not
+be significant and two identical functions can be merged.
+
+Syntax::
+
+ define [linkage] [visibility]
+ [cconv] [ret attrs]
+ <ResultType> @<FunctionName> ([argument list])
+ [fn Attrs] [section "name"] [align N]
+ [gc] { ... }
+
+Aliases
+-------
+
+Aliases act as "second name" for the aliasee value (which can be either
+function, global variable, another alias or bitcast of global value).
+Aliases may have an optional :ref:`linkage type <linkage>`, and an optional
+:ref:`visibility style <visibility>`.
+
+Syntax::
+
+ @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
+
+.. _namedmetadatastructure:
+
+Named Metadata
+--------------
+
+Named metadata is a collection of metadata. :ref:`Metadata
+nodes <metadata>` (but not metadata strings) are the only valid
+operands for a named metadata.
+
+Syntax::
+
+ ; Some unnamed metadata nodes, which are referenced by the named metadata.
+ !0 = metadata !{metadata !"zero"}
+ !1 = metadata !{metadata !"one"}
+ !2 = metadata !{metadata !"two"}
+ ; A named metadata.
+ !name = !{!0, !1, !2}
+
+.. _paramattrs:
+
+Parameter Attributes
+--------------------
+
+The return type and each parameter of a function type may have a set of
+*parameter attributes* associated with them. Parameter attributes are
+used to communicate additional information about the result or
+parameters of a function. Parameter attributes are considered to be part
+of the function, not of the function type, so functions with different
+parameter attributes can have the same function type.
+
+Parameter attributes are simple keywords that follow the type specified.
+If multiple parameter attributes are needed, they are space separated.
+For example:
+
+.. code-block:: llvm
+
+ declare i32 @printf(i8* noalias nocapture, ...)
+ declare i32 @atoi(i8 zeroext)
+ declare signext i8 @returns_signed_char()
+
+Note that any attributes for the function result (``nounwind``,
+``readonly``) come immediately after the argument list.
+
+Currently, only the following parameter attributes are defined:
+
+``zeroext``
+ This indicates to the code generator that the parameter or return
+ value should be zero-extended to the extent required by the target's
+ ABI (which is usually 32-bits, but is 8-bits for a i1 on x86-64) by
+ the caller (for a parameter) or the callee (for a return value).
+``signext``
+ This indicates to the code generator that the parameter or return
+ value should be sign-extended to the extent required by the target's
+ ABI (which is usually 32-bits) by the caller (for a parameter) or
+ the callee (for a return value).
+``inreg``
+ This indicates that this parameter or return value should be treated
+ in a special target-dependent fashion during while emitting code for
+ a function call or return (usually, by putting it in a register as
+ opposed to memory, though some targets use it to distinguish between
+ two different kinds of registers). Use of this attribute is
+ target-specific.
+``byval``
+ This indicates that the pointer parameter should really be passed by
+ value to the function. The attribute implies that a hidden copy of
+ the pointee is made between the caller and the callee, so the callee
+ is unable to modify the value in the caller. This attribute is only
+ valid on LLVM pointer arguments. It is generally used to pass
+ structs and arrays by value, but is also valid on pointers to
+ scalars. The copy is considered to belong to the caller not the
+ callee (for example, ``readonly`` functions should not write to
+ ``byval`` parameters). This is not a valid attribute for return
+ values.
+
+ The byval attribute also supports specifying an alignment with the
+ align attribute. It indicates the alignment of the stack slot to
+ form and the known alignment of the pointer specified to the call
+ site. If the alignment is not specified, then the code generator
+ makes a target-specific assumption.
+
+``sret``
+ This indicates that the pointer parameter specifies the address of a
+ structure that is the return value of the function in the source
+ program. This pointer must be guaranteed by the caller to be valid:
+ loads and stores to the structure may be assumed by the callee to
+ not to trap and to be properly aligned. This may only be applied to
+ the first parameter. This is not a valid attribute for return
+ values.
+``noalias``
+ This indicates that pointer values `*based* <pointeraliasing>` on
+ the argument or return value do not alias pointer values which are
+ not *based* on it, ignoring certain "irrelevant" dependencies. For a
+ call to the parent function, dependencies between memory references
+ from before or after the call and from those during the call are
+ "irrelevant" to the ``noalias`` keyword for the arguments and return
+ value used in that call. The caller shares the responsibility with
+ the callee for ensuring that these requirements are met. For further
+ details, please see the discussion of the NoAlias response in `alias
+ analysis <AliasAnalysis.html#MustMayNo>`_.
+
+ Note that this definition of ``noalias`` is intentionally similar
+ to the definition of ``restrict`` in C99 for function arguments,
+ though it is slightly weaker.
+
+ For function return values, C99's ``restrict`` is not meaningful,
+ while LLVM's ``noalias`` is.
+``nocapture``
+ This indicates that the callee does not make any copies of the
+ pointer that outlive the callee itself. This is not a valid
+ attribute for return values.
+
+.. _nest:
+
+``nest``
+ This indicates that the pointer parameter can be excised using the
+ :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
+ attribute for return values.
+
+.. _gc:
+
+Garbage Collector Names
+-----------------------
+
+Each function may specify a garbage collector name, which is simply a
+string:
+
+.. code-block:: llvm
+
+ define void @f() gc "name" { ... }
+
+The compiler declares the supported values of *name*. Specifying a
+collector which will cause the compiler to alter its output in order to
+support the named garbage collection algorithm.
+
+.. _fnattrs:
+
+Function Attributes
+-------------------
+
+Function attributes are set to communicate additional information about
+a function. Function attributes are considered to be part of the
+function, not of the function type, so functions with different function
+attributes can have the same function type.
+
+Function attributes are simple keywords that follow the type specified.
+If multiple attributes are needed, they are space separated. For
+example:
+
+.. code-block:: llvm
+
+ define void @f() noinline { ... }
+ define void @f() alwaysinline { ... }
+ define void @f() alwaysinline optsize { ... }
+ define void @f() optsize { ... }
+
+``address_safety``
+ This attribute indicates that the address safety analysis is enabled
+ for this function.
+``alignstack(<n>)``
+ This attribute indicates that, when emitting the prologue and
+ epilogue, the backend should forcibly align the stack pointer.
+ Specify the desired alignment, which must be a power of two, in
+ parentheses.
+``alwaysinline``
+ This attribute indicates that the inliner should attempt to inline
+ this function into callers whenever possible, ignoring any active
+ inlining size threshold for this caller.
+``nonlazybind``
+ This attribute suppresses lazy symbol binding for the function. This
+ may make calls to the function faster, at the cost of extra program
+ startup time if the function is not called during program startup.
+``inlinehint``
+ This attribute indicates that the source code contained a hint that
+ inlining this function is desirable (such as the "inline" keyword in
+ C/C++). It is just a hint; it imposes no requirements on the
+ inliner.
+``naked``
+ This attribute disables prologue / epilogue emission for the
+ function. This can have very system-specific consequences.
+``noimplicitfloat``
+ This attributes disables implicit floating point instructions.
+``noinline``
+ This attribute indicates that the inliner should never inline this
+ function in any situation. This attribute may not be used together
+ with the ``alwaysinline`` attribute.
+``noredzone``
+ This attribute indicates that the code generator should not use a
+ red zone, even if the target-specific ABI normally permits it.
+``noreturn``
+ This function attribute indicates that the function never returns
+ normally. This produces undefined behavior at runtime if the
+ function ever does dynamically return.
+``nounwind``
+ This function attribute indicates that the function never returns
+ with an unwind or exceptional control flow. If the function does
+ unwind, its runtime behavior is undefined.
+``optsize``
+ This attribute suggests that optimization passes and code generator
+ passes make choices that keep the code size of this function low,
+ and otherwise do optimizations specifically to reduce code size.
+``readnone``
+ This attribute indicates that the function computes its result (or
+ decides to unwind an exception) based strictly on its arguments,
+ without dereferencing any pointer arguments or otherwise accessing
+ any mutable state (e.g. memory, control registers, etc) visible to
+ caller functions. It does not write through any pointer arguments
+ (including ``byval`` arguments) and never changes any state visible
+ to callers. This means that it cannot unwind exceptions by calling
+ the ``C++`` exception throwing methods.
+``readonly``
+ This attribute indicates that the function does not write through
+ any pointer arguments (including ``byval`` arguments) or otherwise
+ modify any state (e.g. memory, control registers, etc) visible to
+ caller functions. It may dereference pointer arguments and read
+ state that may be set in the caller. A readonly function always
+ returns the same value (or unwinds an exception identically) when
+ called with the same set of arguments and global state. It cannot
+ unwind an exception by calling the ``C++`` exception throwing
+ methods.
+``returns_twice``
+ This attribute indicates that this function can return twice. The C
+ ``setjmp`` is an example of such a function. The compiler disables
+ some optimizations (like tail calls) in the caller of these
+ functions.
+``ssp``
+ This attribute indicates that the function should emit a stack
+ smashing protector. It is in the form of a "canary"—a random value
+ placed on the stack before the local variables that's checked upon
+ return from the function to see if it has been overwritten. A
+ heuristic is used to determine if a function needs stack protectors
+ or not.
+
+ If a function that has an ``ssp`` attribute is inlined into a
+ function that doesn't have an ``ssp`` attribute, then the resulting
+ function will have an ``ssp`` attribute.
+``sspreq``
+ This attribute indicates that the function should *always* emit a
+ stack smashing protector. This overrides the ``ssp`` function
+ attribute.
+
+ If a function that has an ``sspreq`` attribute is inlined into a
+ function that doesn't have an ``sspreq`` attribute or which has an
+ ``ssp`` attribute, then the resulting function will have an
+ ``sspreq`` attribute.
+``uwtable``
+ This attribute indicates that the ABI being targeted requires that
+ an unwind table entry be produce for this function even if we can
+ show that no exceptions passes by it. This is normally the case for
+ the ELF x86-64 abi, but it can be disabled for some compilation
+ units.
+
+.. _moduleasm:
+
+Module-Level Inline Assembly
+----------------------------
+
+Modules may contain "module-level inline asm" blocks, which corresponds
+to the GCC "file scope inline asm" blocks. These blocks are internally
+concatenated by LLVM and treated as a single unit, but may be separated
+in the ``.ll`` file if desired. The syntax is very simple:
+
+.. code-block:: llvm
+
+ module asm "inline asm code goes here"
+ module asm "more can go here"
+
+The strings can contain any character by escaping non-printable
+characters. The escape sequence used is simply "\\xx" where "xx" is the
+two digit hex code for the number.
+
+The inline asm code is simply printed to the machine code .s file when
+assembly code is generated.
+
+Data Layout
+-----------
+
+A module may specify a target specific data layout string that specifies
+how data is to be laid out in memory. The syntax for the data layout is
+simply:
+
+.. code-block:: llvm
+
+ target datalayout = "layout specification"
+
+The *layout specification* consists of a list of specifications
+separated by the minus sign character ('-'). Each specification starts
+with a letter and may include other information after the letter to
+define some aspect of the data layout. The specifications accepted are
+as follows:
+
+``E``
+ Specifies that the target lays out data in big-endian form. That is,
+ the bits with the most significance have the lowest address
+ location.
+``e``
+ Specifies that the target lays out data in little-endian form. That
+ is, the bits with the least significance have the lowest address
+ location.
+``S<size>``
+ Specifies the natural alignment of the stack in bits. Alignment
+ promotion of stack variables is limited to the natural stack
+ alignment to avoid dynamic stack realignment. The stack alignment
+ must be a multiple of 8-bits. If omitted, the natural stack
+ alignment defaults to "unspecified", which does not prevent any
+ alignment promotions.
+``p[n]:<size>:<abi>:<pref>``
+ This specifies the *size* of a pointer and its ``<abi>`` and
+ ``<pref>``\erred alignments for address space ``n``. All sizes are in
+ bits. Specifying the ``<pref>`` alignment is optional. If omitted, the
+ preceding ``:`` should be omitted too. The address space, ``n`` is
+ optional, and if not specified, denotes the default address space 0.
+ The value of ``n`` must be in the range [1,2^23).
+``i<size>:<abi>:<pref>``
+ This specifies the alignment for an integer type of a given bit
+ ``<size>``. The value of ``<size>`` must be in the range [1,2^23).
+``v<size>:<abi>:<pref>``
+ This specifies the alignment for a vector type of a given bit
+ ``<size>``.
+``f<size>:<abi>:<pref>``
+ This specifies the alignment for a floating point type of a given bit
+ ``<size>``. Only values of ``<size>`` that are supported by the target
+ will work. 32 (float) and 64 (double) are supported on all targets; 80
+ or 128 (different flavors of long double) are also supported on some
+ targets.
+``a<size>:<abi>:<pref>``
+ This specifies the alignment for an aggregate type of a given bit
+ ``<size>``.
+``s<size>:<abi>:<pref>``
+ This specifies the alignment for a stack object of a given bit
+ ``<size>``.
+``n<size1>:<size2>:<size3>...``
+ This specifies a set of native integer widths for the target CPU in
+ bits. For example, it might contain ``n32`` for 32-bit PowerPC,
+ ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of
+ this set are considered to support most general arithmetic operations
+ efficiently.
+
+When constructing the data layout for a given target, LLVM starts with a
+default set of specifications which are then (possibly) overridden by
+the specifications in the ``datalayout`` keyword. The default
+specifications are given in this list:
+
+- ``E`` - big endian
+- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment
+- ``p1:32:32:32`` - 32-bit pointers with 32-bit alignment for address
+ space 1
+- ``p2:16:32:32`` - 16-bit pointers with 32-bit alignment for address
+ space 2
+- ``i1:8:8`` - i1 is 8-bit (byte) aligned
+- ``i8:8:8`` - i8 is 8-bit (byte) aligned
+- ``i16:16:16`` - i16 is 16-bit aligned
+- ``i32:32:32`` - i32 is 32-bit aligned
+- ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
+ alignment of 64-bits
+- ``f32:32:32`` - float is 32-bit aligned
+- ``f64:64:64`` - double is 64-bit aligned
+- ``v64:64:64`` - 64-bit vector is 64-bit aligned
+- ``v128:128:128`` - 128-bit vector is 128-bit aligned
+- ``a0:0:1`` - aggregates are 8-bit aligned
+- ``s0:64:64`` - stack objects are 64-bit aligned
+
+When LLVM is determining the alignment for a given type, it uses the
+following rules:
+
+#. If the type sought is an exact match for one of the specifications,
+ that specification is used.
+#. If no match is found, and the type sought is an integer type, then
+ the smallest integer type that is larger than the bitwidth of the
+ sought type is used. If none of the specifications are larger than
+ the bitwidth then the largest integer type is used. For example,
+ given the default specifications above, the i7 type will use the
+ alignment of i8 (next largest) while both i65 and i256 will use the
+ alignment of i64 (largest specified).
+#. If no match is found, and the type sought is a vector type, then the
+ largest vector type that is smaller than the sought vector type will
+ be used as a fall back. This happens because <128 x double> can be
+ implemented in terms of 64 <2 x double>, for example.
+
+The function of the data layout string may not be what you expect.
+Notably, this is not a specification from the frontend of what alignment
+the code generator should use.
+
+Instead, if specified, the target data layout is required to match what
+the ultimate *code generator* expects. This string is used by the
+mid-level optimizers to improve code, and this only works if it matches
+what the ultimate code generator uses. If you would like to generate IR
+that does not embed this target-specific detail into the IR, then you
+don't have to specify the string. This will disable some optimizations
+that require precise layout information, but this also prevents those
+optimizations from introducing target specificity into the IR.
+
+.. _pointeraliasing:
+
+Pointer Aliasing Rules
+----------------------
+
+Any memory access must be done through a pointer value associated with
+an address range of the memory access, otherwise the behavior is
+undefined. Pointer values are associated with address ranges according
+to the following rules:
+
+- A pointer value is associated with the addresses associated with any
+ value it is *based* on.
+- An address of a global variable is associated with the address range
+ of the variable's storage.
+- The result value of an allocation instruction is associated with the
+ address range of the allocated storage.
+- A null pointer in the default address-space is associated with no
+ address.
+- An integer constant other than zero or a pointer value returned from
+ a function not defined within LLVM may be associated with address
+ ranges allocated through mechanisms other than those provided by
+ LLVM. Such ranges shall not overlap with any ranges of addresses
+ allocated by mechanisms provided by LLVM.
+
+A pointer value is *based* on another pointer value according to the
+following rules:
+
+- A pointer value formed from a ``getelementptr`` operation is *based*
+ on the first operand of the ``getelementptr``.
+- The result value of a ``bitcast`` is *based* on the operand of the
+ ``bitcast``.
+- A pointer value formed by an ``inttoptr`` is *based* on all pointer
+ values that contribute (directly or indirectly) to the computation of
+ the pointer's value.
+- The "*based* on" relationship is transitive.
+
+Note that this definition of *"based"* is intentionally similar to the
+definition of *"based"* in C99, though it is slightly weaker.
+
+LLVM IR does not associate types with memory. The result type of a
+``load`` merely indicates the size and alignment of the memory from
+which to load, as well as the interpretation of the value. The first
+operand type of a ``store`` similarly only indicates the size and
+alignment of the store.
+
+Consequently, type-based alias analysis, aka TBAA, aka
+``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR.
+:ref:`Metadata <metadata>` may be used to encode additional information
+which specialized optimization passes may use to implement type-based
+alias analysis.
+
+.. _volatile:
+
+Volatile Memory Accesses
+------------------------
+
+Certain memory accesses, such as :ref:`load <i_load>`'s,
+:ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be
+marked ``volatile``. The optimizers must not change the number of
+volatile operations or change their order of execution relative to other
+volatile operations. The optimizers *may* change the order of volatile
+operations relative to non-volatile operations. This is not Java's
+"volatile" and has no cross-thread synchronization behavior.
+
+.. _memmodel:
+
+Memory Model for Concurrent Operations
+--------------------------------------
+
+The LLVM IR does not define any way to start parallel threads of
+execution or to register signal handlers. Nonetheless, there are
+platform-specific ways to create them, and we define LLVM IR's behavior
+in their presence. This model is inspired by the C++0x memory model.
+
+For a more informal introduction to this model, see the :doc:`Atomics`.
+
+We define a *happens-before* partial order as the least partial order
+that
+
+- Is a superset of single-thread program order, and
+- When a *synchronizes-with* ``b``, includes an edge from ``a`` to
+ ``b``. *Synchronizes-with* pairs are introduced by platform-specific
+ techniques, like pthread locks, thread creation, thread joining,
+ etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering
+ Constraints <ordering>`).
+
+Note that program order does not introduce *happens-before* edges
+between a thread and signals executing inside that thread.
+
+Every (defined) read operation (load instructions, memcpy, atomic
+loads/read-modify-writes, etc.) R reads a series of bytes written by
+(defined) write operations (store instructions, atomic
+stores/read-modify-writes, memcpy, etc.). For the purposes of this
+section, initialized globals are considered to have a write of the
+initializer which is atomic and happens before any other read or write
+of the memory in question. For each byte of a read R, R\ :sub:`byte`
+may see any write to the same byte, except:
+
+- If write\ :sub:`1` happens before write\ :sub:`2`, and
+ write\ :sub:`2` happens before R\ :sub:`byte`, then
+ R\ :sub:`byte` does not see write\ :sub:`1`.
+- If R\ :sub:`byte` happens before write\ :sub:`3`, then
+ R\ :sub:`byte` does not see write\ :sub:`3`.
+
+Given that definition, R\ :sub:`byte` is defined as follows:
+
+- If R is volatile, the result is target-dependent. (Volatile is
+ supposed to give guarantees which can support ``sig_atomic_t`` in
+ C/C++, and may be used for accesses to addresses which do not behave
+ like normal memory. It does not generally provide cross-thread
+ synchronization.)
+- Otherwise, if there is no write to the same byte that happens before
+ R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte.
+- Otherwise, if R\ :sub:`byte` may see exactly one write,
+ R\ :sub:`byte` returns the value written by that write.
+- Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may
+ see are atomic, it chooses one of the values written. See the :ref:`Atomic
+ Memory Ordering Constraints <ordering>` section for additional
+ constraints on how the choice is made.
+- Otherwise R\ :sub:`byte` returns ``undef``.
+
+R returns the value composed of the series of bytes it read. This
+implies that some bytes within the value may be ``undef`` **without**
+the entire value being ``undef``. Note that this only defines the
+semantics of the operation; it doesn't mean that targets will emit more
+than one instruction to read the series of bytes.
+
+Note that in cases where none of the atomic intrinsics are used, this
+model places only one restriction on IR transformations on top of what
+is required for single-threaded execution: introducing a store to a byte
+which might not otherwise be stored is not allowed in general.
+(Specifically, in the case where another thread might write to and read
+from an address, introducing a store can change a load that may see
+exactly one write into a load that may see multiple writes.)
+
+.. _ordering:
+
+Atomic Memory Ordering Constraints
+----------------------------------
+
+Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`,
+:ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`,
+:ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take
+an ordering parameter that determines which other atomic instructions on
+the same address they *synchronize with*. These semantics are borrowed
+from Java and C++0x, but are somewhat more colloquial. If these
+descriptions aren't precise enough, check those specs (see spec
+references in the :doc:`atomics guide <Atomics>`).
+:ref:`fence <i_fence>` instructions treat these orderings somewhat
+differently since they don't take an address. See that instruction's
+documentation for details.
+
+For a simpler introduction to the ordering constraints, see the
+:doc:`Atomics`.
+
+``unordered``
+ The set of values that can be read is governed by the happens-before
+ partial order. A value cannot be read unless some operation wrote
+ it. This is intended to provide a guarantee strong enough to model
+ Java's non-volatile shared variables. This ordering cannot be
+ specified for read-modify-write operations; it is not strong enough
+ to make them atomic in any interesting way.
+``monotonic``
+ In addition to the guarantees of ``unordered``, there is a single
+ total order for modifications by ``monotonic`` operations on each
+ address. All modification orders must be compatible with the
+ happens-before order. There is no guarantee that the modification
+ orders can be combined to a global total order for the whole program
+ (and this often will not be possible). The read in an atomic
+ read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and
+ :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification
+ order immediately before the value it writes. If one atomic read
+ happens before another atomic read of the same address, the later
+ read must see the same value or a later value in the address's
+ modification order. This disallows reordering of ``monotonic`` (or
+ stronger) operations on the same address. If an address is written
+ ``monotonic``-ally by one thread, and other threads ``monotonic``-ally
+ read that address repeatedly, the other threads must eventually see
+ the write. This corresponds to the C++0x/C1x
+ ``memory_order_relaxed``.
+``acquire``
+ In addition to the guarantees of ``monotonic``, a
+ *synchronizes-with* edge may be formed with a ``release`` operation.
+ This is intended to model C++'s ``memory_order_acquire``.
+``release``
+ In addition to the guarantees of ``monotonic``, if this operation
+ writes a value which is subsequently read by an ``acquire``
+ operation, it *synchronizes-with* that operation. (This isn't a
+ complete description; see the C++0x definition of a release
+ sequence.) This corresponds to the C++0x/C1x
+ ``memory_order_release``.
+``acq_rel`` (acquire+release)
+ Acts as both an ``acquire`` and ``release`` operation on its
+ address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``.
+``seq_cst`` (sequentially consistent)
+ In addition to the guarantees of ``acq_rel`` (``acquire`` for an
+ operation which only reads, ``release`` for an operation which only
+ writes), there is a global total order on all
+ sequentially-consistent operations on all addresses, which is
+ consistent with the *happens-before* partial order and with the
+ modification orders of all the affected addresses. Each
+ sequentially-consistent read sees the last preceding write to the
+ same address in this global order. This corresponds to the C++0x/C1x
+ ``memory_order_seq_cst`` and Java volatile.
+
+.. _singlethread:
+
+If an atomic operation is marked ``singlethread``, it only *synchronizes
+with* or participates in modification and seq\_cst total orderings with
+other operations running in the same thread (for example, in signal
+handlers).
+
+.. _fastmath:
+
+Fast-Math Flags
+---------------
+
+LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`,
+:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
+:ref:`frem <i_frem>`) have the following flags that can set to enable
+otherwise unsafe floating point operations
+
+``nnan``
+ No NaNs - Allow optimizations to assume the arguments and result are not
+ NaN. Such optimizations are required to retain defined behavior over
+ NaNs, but the value of the result is undefined.
+
+``ninf``
+ No Infs - Allow optimizations to assume the arguments and result are not
+ +/-Inf. Such optimizations are required to retain defined behavior over
+ +/-Inf, but the value of the result is undefined.
+
+``nsz``
+ No Signed Zeros - Allow optimizations to treat the sign of a zero
+ argument or result as insignificant.
+
+``arcp``
+ Allow Reciprocal - Allow optimizations to use the reciprocal of an
+ argument rather than perform division.
+
+``fast``
+ Fast - Allow algebraically equivalent transformations that may
+ dramatically change results in floating point (e.g. reassociate). This
+ flag implies all the others.
+
+.. _typesystem:
+
+Type System
+===========
+
+The LLVM type system is one of the most important features of the
+intermediate representation. Being typed enables a number of
+optimizations to be performed on the intermediate representation
+directly, without having to do extra analyses on the side before the
+transformation. A strong type system makes it easier to read the
+generated code and enables novel analyses and transformations that are
+not feasible to perform on normal three address code representations.
+
+Type Classifications
+--------------------
+
+The types fall into a few useful classifications:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Classification
+ - Types
+
+ * - :ref:`integer <t_integer>`
+ - ``i1``, ``i2``, ``i3``, ... ``i8``, ... ``i16``, ... ``i32``, ...
+ ``i64``, ...
+
+ * - :ref:`floating point <t_floating>`
+ - ``half``, ``float``, ``double``, ``x86_fp80``, ``fp128``,
+ ``ppc_fp128``
+
+
+ * - first class
+
+ .. _t_firstclass:
+
+ - :ref:`integer <t_integer>`, :ref:`floating point <t_floating>`,
+ :ref:`pointer <t_pointer>`, :ref:`vector <t_vector>`,
+ :ref:`structure <t_struct>`, :ref:`array <t_array>`,
+ :ref:`label <t_label>`, :ref:`metadata <t_metadata>`.
+
+ * - :ref:`primitive <t_primitive>`
+ - :ref:`label <t_label>`,
+ :ref:`void <t_void>`,
+ :ref:`integer <t_integer>`,
+ :ref:`floating point <t_floating>`,
+ :ref:`x86mmx <t_x86mmx>`,
+ :ref:`metadata <t_metadata>`.
+
+ * - :ref:`derived <t_derived>`
+ - :ref:`array <t_array>`,
+ :ref:`function <t_function>`,
+ :ref:`pointer <t_pointer>`,
+ :ref:`structure <t_struct>`,
+ :ref:`vector <t_vector>`,
+ :ref:`opaque <t_opaque>`.
+
+The :ref:`first class <t_firstclass>` types are perhaps the most important.
+Values of these types are the only ones which can be produced by
+instructions.
+
+.. _t_primitive:
+
+Primitive Types
+---------------
+
+The primitive types are the fundamental building blocks of the LLVM
+system.
+
+.. _t_integer:
+
+Integer Type
+^^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The integer type is a very simple type that simply specifies an
+arbitrary bit width for the integer type desired. Any bit width from 1
+bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified.
+
+Syntax:
+"""""""
+
+::
+
+ iN
+
+The number of bits the integer will occupy is specified by the ``N``
+value.
+
+Examples:
+"""""""""
+
++----------------+------------------------------------------------+
+| ``i1`` | a single-bit integer. |
++----------------+------------------------------------------------+
+| ``i32`` | a 32-bit integer. |
++----------------+------------------------------------------------+
+| ``i1942652`` | a really big integer of over 1 million bits. |
++----------------+------------------------------------------------+
+
+.. _t_floating:
+
+Floating Point Types
+^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :header-rows: 1
+
+ * - Type
+ - Description
+
+ * - ``half``
+ - 16-bit floating point value
+
+ * - ``float``
+ - 32-bit floating point value
+
+ * - ``double``
+ - 64-bit floating point value
+
+ * - ``fp128``
+ - 128-bit floating point value (112-bit mantissa)
+
+ * - ``x86_fp80``
+ - 80-bit floating point value (X87)
+
+ * - ``ppc_fp128``
+ - 128-bit floating point value (two 64-bits)
+
+.. _t_x86mmx:
+
+X86mmx Type
+^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The x86mmx type represents a value held in an MMX register on an x86
+machine. The operations allowed on it are quite limited: parameters and
+return values, load and store, and bitcast. User-specified MMX
+instructions are represented as intrinsic or asm calls with arguments
+and/or results of this type. There are no arrays, vectors or constants
+of this type.
+
+Syntax:
+"""""""
+
+::
+
+ x86mmx
+
+.. _t_void:
+
+Void Type
+^^^^^^^^^
+
+Overview:
+"""""""""
+
+The void type does not represent any value and has no size.
+
+Syntax:
+"""""""
+
+::
+
+ void
+
+.. _t_label:
+
+Label Type
+^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The label type represents code labels.
+
+Syntax:
+"""""""
+
+::
+
+ label
+
+.. _t_metadata:
+
+Metadata Type
+^^^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The metadata type represents embedded metadata. No derived types may be
+created from metadata except for :ref:`function <t_function>` arguments.
+
+Syntax:
+"""""""
+
+::
+
+ metadata
+
+.. _t_derived:
+
+Derived Types
+-------------
+
+The real power in LLVM comes from the derived types in the system. This
+is what allows a programmer to represent arrays, functions, pointers,
+and other useful types. Each of these types contain one or more element
+types which may be a primitive type, or another derived type. For
+example, it is possible to have a two dimensional array, using an array
+as the element type of another array.
+
+.. _t_aggregate:
+
+Aggregate Types
+^^^^^^^^^^^^^^^
+
+Aggregate Types are a subset of derived types that can contain multiple
+member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are
+aggregate types. :ref:`Vectors <t_vector>` are not considered to be
+aggregate types.
+
+.. _t_array:
+
+Array Type
+^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The array type is a very simple derived type that arranges elements
+sequentially in memory. The array type requires a size (number of
+elements) and an underlying data type.
+
+Syntax:
+"""""""
+
+::
+
+ [<# elements> x <elementtype>]
+
+The number of elements is a constant integer value; ``elementtype`` may
+be any type with a size.
+
+Examples:
+"""""""""
+
++------------------+--------------------------------------+
+| ``[40 x i32]`` | Array of 40 32-bit integer values. |
++------------------+--------------------------------------+
+| ``[41 x i32]`` | Array of 41 32-bit integer values. |
++------------------+--------------------------------------+
+| ``[4 x i8]`` | Array of 4 8-bit integer values. |
++------------------+--------------------------------------+
+
+Here are some examples of multidimensional arrays:
+
++-----------------------------+----------------------------------------------------------+
+| ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. |
++-----------------------------+----------------------------------------------------------+
+| ``[12 x [10 x float]]`` | 12x10 array of single precision floating point values. |
++-----------------------------+----------------------------------------------------------+
+| ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. |
++-----------------------------+----------------------------------------------------------+
+
+There is no restriction on indexing beyond the end of the array implied
+by a static type (though there are restrictions on indexing beyond the
+bounds of an allocated object in some cases). This means that
+single-dimension 'variable sized array' addressing can be implemented in
+LLVM with a zero length array type. An implementation of 'pascal style
+arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for
+example.
+
+.. _t_function:
+
+Function Type
+^^^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The function type can be thought of as a function signature. It consists
+of a return type and a list of formal parameter types. The return type
+of a function type is a first class type or a void type.
+
+Syntax:
+"""""""
+
+::
+
+ <returntype> (<parameter list>)
+
+...where '``<parameter list>``' is a comma-separated list of type
+specifiers. Optionally, the parameter list may include a type ``...``,
+which indicates that the function takes a variable number of arguments.
+Variable argument functions can access their arguments with the
+:ref:`variable argument handling intrinsic <int_varargs>` functions.
+'``<returntype>``' is any type except :ref:`label <t_label>`.
+
+Examples:
+"""""""""
+
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _t_struct:
+
+Structure Type
+^^^^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The structure type is used to represent a collection of data members
+together in memory. The elements of a structure may be any type that has
+a size.
+
+Structures in memory are accessed using '``load``' and '``store``' by
+getting a pointer to a field with the '``getelementptr``' instruction.
+Structures in registers are accessed using the '``extractvalue``' and
+'``insertvalue``' instructions.
+
+Structures may optionally be "packed" structures, which indicate that
+the alignment of the struct is one byte, and that there is no padding
+between the elements. In non-packed structs, padding between field types
+is inserted as defined by the DataLayout string in the module, which is
+required to match what the underlying code generator expects.
+
+Structures can either be "literal" or "identified". A literal structure
+is defined inline with other types (e.g. ``{i32, i32}*``) whereas
+identified types are always defined at the top level with a name.
+Literal types are uniqued by their contents and can never be recursive
+or opaque since there is no way to write one. Identified types can be
+recursive, can be opaqued, and are never uniqued.
+
+Syntax:
+"""""""
+
+::
+
+ %T1 = type { <type list> } ; Identified normal struct type
+ %T2 = type <{ <type list> }> ; Identified packed struct type
+
+Examples:
+"""""""""
+
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values |
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``{ float, i32 (i32) * }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32``, returning an ``i32``. |
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. |
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _t_opaque:
+
+Opaque Structure Types
+^^^^^^^^^^^^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+Opaque structure types are used to represent named structure types that
+do not have a body specified. This corresponds (for example) to the C
+notion of a forward declared structure.
+
+Syntax:
+"""""""
+
+::
+
+ %X = type opaque
+ %52 = type opaque
+
+Examples:
+"""""""""
+
++--------------+-------------------+
+| ``opaque`` | An opaque type. |
++--------------+-------------------+
+
+.. _t_pointer:
+
+Pointer Type
+^^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+The pointer type is used to specify memory locations. Pointers are
+commonly used to reference objects in memory.
+
+Pointer types may have an optional address space attribute defining the
+numbered address space where the pointed-to object resides. The default
+address space is number zero. The semantics of non-zero address spaces
+are target-specific.
+
+Note that LLVM does not permit pointers to void (``void*``) nor does it
+permit pointers to labels (``label*``). Use ``i8*`` instead.
+
+Syntax:
+"""""""
+
+::
+
+ <type> *
+
+Examples:
+"""""""""
+
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+
+.. _t_vector:
+
+Vector Type
+^^^^^^^^^^^
+
+Overview:
+"""""""""
+
+A vector type is a simple derived type that represents a vector of
+elements. Vector types are used when multiple primitive data are
+operated in parallel using a single instruction (SIMD). A vector type
+requires a size (number of elements) and an underlying primitive data
+type. Vector types are considered :ref:`first class <t_firstclass>`.
+
+Syntax:
+"""""""
+
+::
+
+ < <# elements> x <elementtype> >
+
+The number of elements is a constant integer value larger than 0;
+elementtype may be any integer or floating point type, or a pointer to
+these types. Vectors of size zero are not allowed.
+
+Examples:
+"""""""""
+
++-------------------+--------------------------------------------------+
+| ``<4 x i32>`` | Vector of 4 32-bit integer values. |
++-------------------+--------------------------------------------------+
+| ``<8 x float>`` | Vector of 8 32-bit floating-point values. |
++-------------------+--------------------------------------------------+
+| ``<2 x i64>`` | Vector of 2 64-bit integer values. |
++-------------------+--------------------------------------------------+
+| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. |
++-------------------+--------------------------------------------------+
+
+Constants
+=========
+
+LLVM has several different basic types of constants. This section
+describes them all and their syntax.
+
+Simple Constants
+----------------
+
+**Boolean constants**
+ The two strings '``true``' and '``false``' are both valid constants
+ of the ``i1`` type.
+**Integer constants**
+ Standard integers (such as '4') are constants of the
+ :ref:`integer <t_integer>` type. Negative numbers may be used with
+ integer types.
+**Floating point constants**
+ Floating point constants use standard decimal notation (e.g.
+ 123.421), exponential notation (e.g. 1.23421e+2), or a more precise
+ hexadecimal notation (see below). The assembler requires the exact
+ decimal value of a floating-point constant. For example, the
+ assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating
+ decimal in binary. Floating point constants must have a :ref:`floating
+ point <t_floating>` type.
+**Null pointer constants**
+ The identifier '``null``' is recognized as a null pointer constant
+ and must be of :ref:`pointer type <t_pointer>`.
+
+The one non-intuitive notation for constants is the hexadecimal form of
+floating point constants. For example, the form
+'``double 0x432ff973cafa8000``' is equivalent to (but harder to read
+than) '``double 4.5e+15``'. The only time hexadecimal floating point
+constants are required (and the only time that they are generated by the
+disassembler) is when a floating point constant must be emitted but it
+cannot be represented as a decimal floating point number in a reasonable
+number of digits. For example, NaN's, infinities, and other special
+values are represented in their IEEE hexadecimal format so that assembly
+and disassembly do not cause any bits to change in the constants.
+
+When using the hexadecimal form, constants of types half, float, and
+double are represented using the 16-digit form shown above (which
+matches the IEEE754 representation for double); half and float values
+must, however, be exactly representable as IEE754 half and single
+precision, respectively. Hexadecimal format is always used for long
+double, and there are three forms of long double. The 80-bit format used
+by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The
+128-bit format used by PowerPC (two adjacent doubles) is represented by
+``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is
+represented by ``0xL`` followed by 32 hexadecimal digits; no currently
+supported target uses this format. Long doubles will only work if they
+match the long double format on your target. The IEEE 16-bit format
+(half precision) is represented by ``0xH`` followed by 4 hexadecimal
+digits. All hexadecimal formats are big-endian (sign bit at the left).
+
+There are no constants of type x86mmx.
+
+Complex Constants
+-----------------
+
+Complex constants are a (potentially recursive) combination of simple
+constants and smaller complex constants.
+
+**Structure constants**
+ Structure constants are represented with notation similar to
+ structure type definitions (a comma separated list of elements,
+ surrounded by braces (``{}``)). For example:
+ "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as
+ "``@G = external global i32``". Structure constants must have
+ :ref:`structure type <t_struct>`, and the number and types of elements
+ must match those specified by the type.
+**Array constants**
+ Array constants are represented with notation similar to array type
+ definitions (a comma separated list of elements, surrounded by
+ square brackets (``[]``)). For example:
+ "``[ i32 42, i32 11, i32 74 ]``". Array constants must have
+ :ref:`array type <t_array>`, and the number and types of elements must
+ match those specified by the type.
+**Vector constants**
+ Vector constants are represented with notation similar to vector
+ type definitions (a comma separated list of elements, surrounded by
+ less-than/greater-than's (``<>``)). For example:
+ "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants
+ must have :ref:`vector type <t_vector>`, and the number and types of
+ elements must match those specified by the type.
+**Zero initialization**
+ The string '``zeroinitializer``' can be used to zero initialize a
+ value to zero of *any* type, including scalar and
+ :ref:`aggregate <t_aggregate>` types. This is often used to avoid
+ having to print large zero initializers (e.g. for large arrays) and
+ is always exactly equivalent to using explicit zero initializers.
+**Metadata node**
+ A metadata node is a structure-like constant with :ref:`metadata
+ type <t_metadata>`. For example:
+ "``metadata !{ i32 0, metadata !"test" }``". Unlike other
+ constants that are meant to be interpreted as part of the
+ instruction stream, metadata is a place to attach additional
+ information such as debug info.
+
+Global Variable and Function Addresses
+--------------------------------------
+
+The addresses of :ref:`global variables <globalvars>` and
+:ref:`functions <functionstructure>` are always implicitly valid
+(link-time) constants. These constants are explicitly referenced when
+the :ref:`identifier for the global <identifiers>` is used and always have
+:ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM
+file:
+
+.. code-block:: llvm
+
+ @X = global i32 17
+ @Y = global i32 42
+ @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
+
+.. _undefvalues:
+
+Undefined Values
+----------------
+
+The string '``undef``' can be used anywhere a constant is expected, and
+indicates that the user of the value may receive an unspecified
+bit-pattern. Undefined values may be of any type (other than '``label``'
+or '``void``') and be used anywhere a constant is permitted.
+
+Undefined values are useful because they indicate to the compiler that
+the program is well defined no matter what value is used. This gives the
+compiler more freedom to optimize. Here are some examples of
+(potentially surprising) transformations that are valid (in pseudo IR):
+
+.. code-block:: llvm
+
+ %A = add %X, undef
+ %B = sub %X, undef
+ %C = xor %X, undef
+ Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+
+This is safe because all of the output bits are affected by the undef
+bits. Any output bit can have a zero or one depending on the input bits.
+
+.. code-block:: llvm
+
+ %A = or %X, undef
+ %B = and %X, undef
+ Safe:
+ %A = -1
+ %B = 0
+ Unsafe:
+ %A = undef
+ %B = undef
+
+These logical operations have bits that are not always affected by the
+input. For example, if ``%X`` has a zero bit, then the output of the
+'``and``' operation will always be a zero for that bit, no matter what
+the corresponding bit from the '``undef``' is. As such, it is unsafe to
+optimize or assume that the result of the '``and``' is '``undef``'.
+However, it is safe to assume that all bits of the '``undef``' could be
+0, and optimize the '``and``' to 0. Likewise, it is safe to assume that
+all the bits of the '``undef``' operand to the '``or``' could be set,
+allowing the '``or``' to be folded to -1.
+
+.. code-block:: llvm
+
+ %A = select undef, %X, %Y
+ %B = select undef, 42, %Y
+ %C = select %X, %Y, undef
+ Safe:
+ %A = %X (or %Y)
+ %B = 42 (or %Y)
+ %C = %Y
+ Unsafe:
+ %A = undef
+ %B = undef
+ %C = undef
+
+This set of examples shows that undefined '``select``' (and conditional
+branch) conditions can go *either way*, but they have to come from one
+of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were
+both known to have a clear low bit, then ``%A`` would have to have a
+cleared low bit. However, in the ``%C`` example, the optimizer is
+allowed to assume that the '``undef``' operand could be the same as
+``%Y``, allowing the whole '``select``' to be eliminated.
+
+.. code-block:: llvm
+
+ %A = xor undef, undef
+
+ %B = undef
+ %C = xor %B, %B
+
+ %D = undef
+ %E = icmp lt %D, 4
+ %F = icmp gte %D, 4
+
+ Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+ %D = undef
+ %E = undef
+ %F = undef
+
+This example points out that two '``undef``' operands are not
+necessarily the same. This can be surprising to people (and also matches
+C semantics) where they assume that "``X^X``" is always zero, even if
+``X`` is undefined. This isn't true for a number of reasons, but the
+short answer is that an '``undef``' "variable" can arbitrarily change
+its value over its "live range". This is true because the variable
+doesn't actually *have a live range*. Instead, the value is logically
+read from arbitrary registers that happen to be around when needed, so
+the value is not necessarily consistent over time. In fact, ``%A`` and
+``%C`` need to have the same semantics or the core LLVM "replace all
+uses with" concept would not hold.
+
+.. code-block:: llvm
+
+ %A = fdiv undef, %X
+ %B = fdiv %X, undef
+ Safe:
+ %A = undef
+ b: unreachable
+
+These examples show the crucial difference between an *undefined value*
+and *undefined behavior*. An undefined value (like '``undef``') is
+allowed to have an arbitrary bit-pattern. This means that the ``%A``
+operation can be constant folded to '``undef``', because the '``undef``'
+could be an SNaN, and ``fdiv`` is not (currently) defined on SNaN's.
+However, in the second example, we can make a more aggressive
+assumption: because the ``undef`` is allowed to be an arbitrary value,
+we are allowed to assume that it could be zero. Since a divide by zero
+has *undefined behavior*, we are allowed to assume that the operation
+does not execute at all. This allows us to delete the divide and all
+code after it. Because the undefined operation "can't happen", the
+optimizer can assume that it occurs in dead code.
+
+.. code-block:: llvm
+
+ a: store undef -> %X
+ b: store %X -> undef
+ Safe:
+ a: <deleted>
+ b: unreachable
+
+These examples reiterate the ``fdiv`` example: a store *of* an undefined
+value can be assumed to not have any effect; we can assume that the
+value is overwritten with bits that happen to match what was already
+there. However, a store *to* an undefined location could clobber
+arbitrary memory, therefore, it has undefined behavior.
+
+.. _poisonvalues:
+
+Poison Values
+-------------
+
+Poison values are similar to :ref:`undef values <undefvalues>`, however
+they also represent the fact that an instruction or constant expression
+which cannot evoke side effects has nevertheless detected a condition
+which results in undefined behavior.
+
+There is currently no way of representing a poison value in the IR; they
+only exist when produced by operations such as :ref:`add <i_add>` with
+the ``nsw`` flag.
+
+Poison value behavior is defined in terms of value *dependence*:
+
+- Values other than :ref:`phi <i_phi>` nodes depend on their operands.
+- :ref:`Phi <i_phi>` nodes depend on the operand corresponding to
+ their dynamic predecessor basic block.
+- Function arguments depend on the corresponding actual argument values
+ in the dynamic callers of their functions.
+- :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>`
+ instructions that dynamically transfer control back to them.
+- :ref:`Invoke <i_invoke>` instructions depend on the
+ :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing
+ call instructions that dynamically transfer control back to them.
+- Non-volatile loads and stores depend on the most recent stores to all
+ of the referenced memory addresses, following the order in the IR
+ (including loads and stores implied by intrinsics such as
+ :ref:`@llvm.memcpy <int_memcpy>`.)
+- An instruction with externally visible side effects depends on the
+ most recent preceding instruction with externally visible side
+ effects, following the order in the IR. (This includes :ref:`volatile
+ operations <volatile>`.)
+- An instruction *control-depends* on a :ref:`terminator
+ instruction <terminators>` if the terminator instruction has
+ multiple successors and the instruction is always executed when
+ control transfers to one of the successors, and may not be executed
+ when control is transferred to another.
+- Additionally, an instruction also *control-depends* on a terminator
+ instruction if the set of instructions it otherwise depends on would
+ be different if the terminator had transferred control to a different
+ successor.
+- Dependence is transitive.
+
+Poison Values have the same behavior as :ref:`undef values <undefvalues>`,
+with the additional affect that any instruction which has a *dependence*
+on a poison value has undefined behavior.
+
+Here are some examples:
+
+.. code-block:: llvm
+
+ entry:
+ %poison = sub nuw i32 0, 1 ; Results in a poison value.
+ %still_poison = and i32 %poison, 0 ; 0, but also poison.
+ %poison_yet_again = getelementptr i32* @h, i32 %still_poison
+ store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned
+
+ store i32 %poison, i32* @g ; Poison value stored to memory.
+ %poison2 = load i32* @g ; Poison value loaded back from memory.
+
+ store volatile i32 %poison, i32* @g ; External observation; undefined behavior.
+
+ %narrowaddr = bitcast i32* @g to i16*
+ %wideaddr = bitcast i32* @g to i64*
+ %poison3 = load i16* %narrowaddr ; Returns a poison value.
+ %poison4 = load i64* %wideaddr ; Returns a poison value.
+
+ %cmp = icmp slt i32 %poison, 0 ; Returns a poison value.
+ br i1 %cmp, label %true, label %end ; Branch to either destination.
+
+ true:
+ store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so
+ ; it has undefined behavior.
+ br label %end
+
+ end:
+ %p = phi i32 [ 0, %entry ], [ 1, %true ]
+ ; Both edges into this PHI are
+ ; control-dependent on %cmp, so this
+ ; always results in a poison value.
+
+ store volatile i32 0, i32* @g ; This would depend on the store in %true
+ ; if %cmp is true, or the store in %entry
+ ; otherwise, so this is undefined behavior.
+
+ br i1 %cmp, label %second_true, label %second_end
+ ; The same branch again, but this time the
+ ; true block doesn't have side effects.
+
+ second_true:
+ ; No side effects!
+ ret void
+
+ second_end:
+ store volatile i32 0, i32* @g ; This time, the instruction always depends
+ ; on the store in %end. Also, it is
+ ; control-equivalent to %end, so this is
+ ; well-defined (ignoring earlier undefined
+ ; behavior in this example).
+
+.. _blockaddress:
+
+Addresses of Basic Blocks
+-------------------------
+
+``blockaddress(@function, %block)``
+
+The '``blockaddress``' constant computes the address of the specified
+basic block in the specified function, and always has an ``i8*`` type.
+Taking the address of the entry block is illegal.
+
+This value only has defined behavior when used as an operand to the
+':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons
+against null. Pointer equality tests between labels addresses results in
+undefined behavior — though, again, comparison against null is ok, and
+no label is equal to the null pointer. This may be passed around as an
+opaque pointer sized value as long as the bits are not inspected. This
+allows ``ptrtoint`` and arithmetic to be performed on these values so
+long as the original value is reconstituted before the ``indirectbr``
+instruction.
+
+Finally, some targets may provide defined semantics when using the value
+as the operand to an inline assembly, but that is target specific.
+
+Constant Expressions
+--------------------
+
+Constant expressions are used to allow expressions involving other
+constants to be used as constants. Constant expressions may be of any
+:ref:`first class <t_firstclass>` type and may involve any LLVM operation
+that does not have side effects (e.g. load and call are not supported).
+The following is the syntax for constant expressions:
+
+``trunc (CST to TYPE)``
+ Truncate a constant to another type. The bit size of CST must be
+ larger than the bit size of TYPE. Both types must be integers.
+``zext (CST to TYPE)``
+ Zero extend a constant to another type. The bit size of CST must be
+ smaller than the bit size of TYPE. Both types must be integers.
+``sext (CST to TYPE)``
+ Sign extend a constant to another type. The bit size of CST must be
+ smaller than the bit size of TYPE. Both types must be integers.
+``fptrunc (CST to TYPE)``
+ Truncate a floating point constant to another floating point type.
+ The size of CST must be larger than the size of TYPE. Both types
+ must be floating point.
+``fpext (CST to TYPE)``
+ Floating point extend a constant to another type. The size of CST
+ must be smaller or equal to the size of TYPE. Both types must be
+ floating point.
+``fptoui (CST to TYPE)``
+ Convert a floating point constant to the corresponding unsigned
+ integer constant. TYPE must be a scalar or vector integer type. CST
+ must be of scalar or vector floating point type. Both CST and TYPE
+ must be scalars, or vectors of the same number of elements. If the
+ value won't fit in the integer type, the results are undefined.
+``fptosi (CST to TYPE)``
+ Convert a floating point constant to the corresponding signed
+ integer constant. TYPE must be a scalar or vector integer type. CST
+ must be of scalar or vector floating point type. Both CST and TYPE
+ must be scalars, or vectors of the same number of elements. If the
+ value won't fit in the integer type, the results are undefined.
+``uitofp (CST to TYPE)``
+ Convert an unsigned integer constant to the corresponding floating
+ point constant. TYPE must be a scalar or vector floating point type.
+ CST must be of scalar or vector integer type. Both CST and TYPE must
+ be scalars, or vectors of the same number of elements. If the value
+ won't fit in the floating point type, the results are undefined.
+``sitofp (CST to TYPE)``
+ Convert a signed integer constant to the corresponding floating
+ point constant. TYPE must be a scalar or vector floating point type.
+ CST must be of scalar or vector integer type. Both CST and TYPE must
+ be scalars, or vectors of the same number of elements. If the value
+ won't fit in the floating point type, the results are undefined.
+``ptrtoint (CST to TYPE)``
+ Convert a pointer typed constant to the corresponding integer
+ constant ``TYPE`` must be an integer type. ``CST`` must be of
+ pointer type. The ``CST`` value is zero extended, truncated, or
+ unchanged to make it fit in ``TYPE``.
+``inttoptr (CST to TYPE)``
+ Convert an integer constant to a pointer constant. TYPE must be a
+ pointer type. CST must be of integer type. The CST value is zero
+ extended, truncated, or unchanged to make it fit in a pointer size.
+ This one is *really* dangerous!
+``bitcast (CST to TYPE)``
+ Convert a constant, CST, to another TYPE. The constraints of the
+ operands are the same as those for the :ref:`bitcast
+ instruction <i_bitcast>`.
+``getelementptr (CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)``
+ Perform the :ref:`getelementptr operation <i_getelementptr>` on
+ constants. As with the :ref:`getelementptr <i_getelementptr>`
+ instruction, the index list may have zero or more indexes, which are
+ required to make sense for the type of "CSTPTR".
+``select (COND, VAL1, VAL2)``
+ Perform the :ref:`select operation <i_select>` on constants.
+``icmp COND (VAL1, VAL2)``
+ Performs the :ref:`icmp operation <i_icmp>` on constants.
+``fcmp COND (VAL1, VAL2)``
+ Performs the :ref:`fcmp operation <i_fcmp>` on constants.
+``extractelement (VAL, IDX)``
+ Perform the :ref:`extractelement operation <i_extractelement>` on
+ constants.
+``insertelement (VAL, ELT, IDX)``
+ Perform the :ref:`insertelement operation <i_insertelement>` on
+ constants.
+``shufflevector (VEC1, VEC2, IDXMASK)``
+ Perform the :ref:`shufflevector operation <i_shufflevector>` on
+ constants.
+``extractvalue (VAL, IDX0, IDX1, ...)``
+ Perform the :ref:`extractvalue operation <i_extractvalue>` on
+ constants. The index list is interpreted in a similar manner as
+ indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At
+ least one index value must be specified.
+``insertvalue (VAL, ELT, IDX0, IDX1, ...)``
+ Perform the :ref:`insertvalue operation <i_insertvalue>` on constants.
+ The index list is interpreted in a similar manner as indices in a
+ ':ref:`getelementptr <i_getelementptr>`' operation. At least one index
+ value must be specified.
+``OPCODE (LHS, RHS)``
+ Perform the specified operation of the LHS and RHS constants. OPCODE
+ may be any of the :ref:`binary <binaryops>` or :ref:`bitwise
+ binary <bitwiseops>` operations. The constraints on operands are
+ the same as those for the corresponding instruction (e.g. no bitwise
+ operations on floating point values are allowed).
+
+Other Values
+============
+
+Inline Assembler Expressions
+----------------------------
+
+LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level
+Inline Assembly <moduleasm>`) through the use of a special value. This
+value represents the inline assembler as a string (containing the
+instructions to emit), a list of operand constraints (stored as a
+string), a flag that indicates whether or not the inline asm expression
+has side effects, and a flag indicating whether the function containing
+the asm needs to align its stack conservatively. An example inline
+assembler expression is:
+
+.. code-block:: llvm
+
+ i32 (i32) asm "bswap $0", "=r,r"
+
+Inline assembler expressions may **only** be used as the callee operand
+of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction.
+Thus, typically we have:
+
+.. code-block:: llvm
+
+ %X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
+
+Inline asms with side effects not visible in the constraint list must be
+marked as having side effects. This is done through the use of the
+'``sideeffect``' keyword, like so:
+
+.. code-block:: llvm
+
+ call void asm sideeffect "eieio", ""()
+
+In some cases inline asms will contain code that will not work unless
+the stack is aligned in some way, such as calls or SSE instructions on
+x86, yet will not contain code that does that alignment within the asm.
+The compiler should make conservative assumptions about what the asm
+might contain and should generate its usual stack alignment code in the
+prologue if the '``alignstack``' keyword is present:
+
+.. code-block:: llvm
+
+ call void asm alignstack "eieio", ""()
+
+Inline asms also support using non-standard assembly dialects. The
+assumed dialect is ATT. When the '``inteldialect``' keyword is present,
+the inline asm is using the Intel dialect. Currently, ATT and Intel are
+the only supported dialects. An example is:
+
+.. code-block:: llvm
+
+ call void asm inteldialect "eieio", ""()
+
+If multiple keywords appear the '``sideeffect``' keyword must come
+first, the '``alignstack``' keyword second and the '``inteldialect``'
+keyword last.
+
+Inline Asm Metadata
+^^^^^^^^^^^^^^^^^^^
+
+The call instructions that wrap inline asm nodes may have a
+"``!srcloc``" MDNode attached to it that contains a list of constant
+integers. If present, the code generator will use the integer as the
+location cookie value when report errors through the ``LLVMContext``
+error reporting mechanisms. This allows a front-end to correlate backend
+errors that occur with inline asm back to the source code that produced
+it. For example:
+
+.. code-block:: llvm
+
+ call void asm sideeffect "something bad", ""(), !srcloc !42
+ ...
+ !42 = !{ i32 1234567 }
+
+It is up to the front-end to make sense of the magic numbers it places
+in the IR. If the MDNode contains multiple constants, the code generator
+will use the one that corresponds to the line of the asm that the error
+occurs on.
+
+.. _metadata:
+
+Metadata Nodes and Metadata Strings
+-----------------------------------
+
+LLVM IR allows metadata to be attached to instructions in the program
+that can convey extra information about the code to the optimizers and
+code generator. One example application of metadata is source-level
+debug information. There are two metadata primitives: strings and nodes.
+All metadata has the ``metadata`` type and is identified in syntax by a
+preceding exclamation point ('``!``').
+
+A metadata string is a string surrounded by double quotes. It can
+contain any character by escaping non-printable characters with
+"``\xx``" where "``xx``" is the two digit hex code. For example:
+"``!"test\00"``".
+
+Metadata nodes are represented with notation similar to structure
+constants (a comma separated list of elements, surrounded by braces and
+preceded by an exclamation point). Metadata nodes can have any values as
+their operand. For example:
+
+.. code-block:: llvm
+
+ !{ metadata !"test\00", i32 10}
+
+A :ref:`named metadata <namedmetadatastructure>` is a collection of
+metadata nodes, which can be looked up in the module symbol table. For
+example:
+
+.. code-block:: llvm
+
+ !foo = metadata !{!4, !3}
+
+Metadata can be used as function arguments. Here ``llvm.dbg.value``
+function is using two metadata arguments:
+
+.. code-block:: llvm
+
+ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
+
+Metadata can be attached with an instruction. Here metadata ``!21`` is
+attached to the ``add`` instruction using the ``!dbg`` identifier:
+
+.. code-block:: llvm
+
+ %indvar.next = add i64 %indvar, 1, !dbg !21
+
+More information about specific metadata nodes recognized by the
+optimizers and code generator is found below.
+
+'``tbaa``' Metadata
+^^^^^^^^^^^^^^^^^^^
+
+In LLVM IR, memory does not have types, so LLVM's own type system is not
+suitable for doing TBAA. Instead, metadata is added to the IR to
+describe a type system of a higher level language. This can be used to
+implement typical C/C++ TBAA, but it can also be used to implement
+custom alias analysis behavior for other languages.
+
+The current metadata format is very simple. TBAA metadata nodes have up
+to three fields, e.g.:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !"an example type tree" }
+ !1 = metadata !{ metadata !"int", metadata !0 }
+ !2 = metadata !{ metadata !"float", metadata !0 }
+ !3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
+
+The first field is an identity field. It can be any value, usually a
+metadata string, which uniquely identifies the type. The most important
+name in the tree is the name of the root node. Two trees with different
+root node names are entirely disjoint, even if they have leaves with
+common names.
+
+The second field identifies the type's parent node in the tree, or is
+null or omitted for a root node. A type is considered to alias all of
+its descendants and all of its ancestors in the tree. Also, a type is
+considered to alias all types in other trees, so that bitcode produced
+from multiple front-ends is handled conservatively.
+
+If the third field is present, it's an integer which if equal to 1
+indicates that the type is "constant" (meaning
+``pointsToConstantMemory`` should return true; see `other useful
+AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_).
+
+'``tbaa.struct``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :ref:`llvm.memcpy <int_memcpy>` is often used to implement
+aggregate assignment operations in C and similar languages, however it
+is defined to copy a contiguous region of memory, which is more than
+strictly necessary for aggregate types which contain holes due to
+padding. Also, it doesn't contain any TBAA information about the fields
+of the aggregate.
+
+``!tbaa.struct`` metadata can describe which memory subregions in a
+memcpy are padding and what the TBAA tags of the struct are.
+
+The current metadata format is very simple. ``!tbaa.struct`` metadata
+nodes are a list of operands which are in conceptual groups of three.
+For each group of three, the first operand gives the byte offset of a
+field in bytes, the second gives its size in bytes, and the third gives
+its tbaa tag. e.g.:
+
+.. code-block:: llvm
+
+ !4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }
+
+This describes a struct with two fields. The first is at offset 0 bytes
+with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
+and has size 4 bytes and has tbaa tag !2.
+
+Note that the fields need not be contiguous. In this example, there is a
+4 byte gap between the two fields. This gap represents padding which
+does not carry useful data and need not be preserved.
+
+'``fpmath``' Metadata
+^^^^^^^^^^^^^^^^^^^^^
+
+``fpmath`` metadata may be attached to any instruction of floating point
+type. It can be used to express the maximum acceptable error in the
+result of that instruction, in ULPs, thus potentially allowing the
+compiler to use a more efficient but less accurate method of computing
+it. ULP is defined as follows:
+
+ If ``x`` is a real number that lies between two finite consecutive
+ floating-point numbers ``a`` and ``b``, without being equal to one
+ of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the
+ distance between the two non-equal finite floating-point numbers
+ nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``.
+
+The metadata node shall consist of a single positive floating point
+number representing the maximum relative error, for example:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
+
+'``range``' Metadata
+^^^^^^^^^^^^^^^^^^^^
+
+``range`` metadata may be attached only to loads of integer types. It
+expresses the possible ranges the loaded value is in. The ranges are
+represented with a flattened list of integers. The loaded value is known
+to be in the union of the ranges defined by each consecutive pair. Each
+pair has the following properties:
+
+- The type must match the type loaded by the instruction.
+- The pair ``a,b`` represents the range ``[a,b)``.
+- Both ``a`` and ``b`` are constants.
+- The range is allowed to wrap.
+- The range should not represent the full or empty set. That is,
+ ``a!=b``.
+
+In addition, the pairs must be in signed order of the lower bound and
+they must be non-contiguous.
+
+Examples:
+
+.. code-block:: llvm
+
+ %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
+ %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
+ %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
+ %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5
+ ...
+ !0 = metadata !{ i8 0, i8 2 }
+ !1 = metadata !{ i8 255, i8 2 }
+ !2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
+ !3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
+
+Module Flags Metadata
+=====================
+
+Information about the module as a whole is difficult to convey to LLVM's
+subsystems. The LLVM IR isn't sufficient to transmit this information.
+The ``llvm.module.flags`` named metadata exists in order to facilitate
+this. These flags are in the form of key / value pairs — much like a
+dictionary — making it easy for any subsystem who cares about a flag to
+look it up.
+
+The ``llvm.module.flags`` metadata contains a list of metadata triplets.
+Each triplet has the following form:
+
+- The first element is a *behavior* flag, which specifies the behavior
+ when two (or more) modules are merged together, and it encounters two
+ (or more) metadata with the same ID. The supported behaviors are
+ described below.
+- The second element is a metadata string that is a unique ID for the
+ metadata. How each ID is interpreted is documented below.
+- The third element is the value of the flag.
+
+When two (or more) modules are merged together, the resulting
+``llvm.module.flags`` metadata is the union of the modules'
+``llvm.module.flags`` metadata. The only exception being a flag with the
+*Override* behavior, which may override another flag's value (see
+below).
+
+The following behaviors are supported:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 90
+
+ * - Value
+ - Behavior
+
+ * - 1
+ - **Error**
+ Emits an error if two values disagree. It is an error to have an
+ ID with both an Error and a Warning behavior.
+
+ * - 2
+ - **Warning**
+ Emits a warning if two values disagree.
+
+ * - 3
+ - **Require**
+ Emits an error when the specified value is not present or doesn't
+ have the specified value. It is an error for two (or more)
+ ``llvm.module.flags`` with the same ID to have the Require behavior
+ but different values. There may be multiple Require flags per ID.
+
+ * - 4
+ - **Override**
+ Uses the specified value if the two values disagree. It is an
+ error for two (or more) ``llvm.module.flags`` with the same ID
+ to have the Override behavior but different values.
+
+An example of module flags:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ i32 1, metadata !"foo", i32 1 }
+ !1 = metadata !{ i32 4, metadata !"bar", i32 37 }
+ !2 = metadata !{ i32 2, metadata !"qux", i32 42 }
+ !3 = metadata !{ i32 3, metadata !"qux",
+ metadata !{
+ metadata !"foo", i32 1
+ }
+ }
+ !llvm.module.flags = !{ !0, !1, !2, !3 }
+
+- Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior
+ if two or more ``!"foo"`` flags are seen is to emit an error if their
+ values are not equal.
+
+- Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The
+ behavior if two or more ``!"bar"`` flags are seen is to use the value
+ '37' if their values are not equal.
+
+- Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The
+ behavior if two or more ``!"qux"`` flags are seen is to emit a
+ warning if their values are not equal.
+
+- Metadata ``!3`` has the ID ``!"qux"`` and the value:
+
+ ::
+
+ metadata !{ metadata !"foo", i32 1 }
+
+ The behavior is to emit an error if the ``llvm.module.flags`` does
+ not contain a flag with the ID ``!"foo"`` that has the value '1'. If
+ two or more ``!"qux"`` flags exist, then they must have the same
+ value or an error will be issued.
+
+Objective-C Garbage Collection Module Flags Metadata
+----------------------------------------------------
+
+On the Mach-O platform, Objective-C stores metadata about garbage
+collection in a special section called "image info". The metadata
+consists of a version number and a bitmask specifying what types of
+garbage collection are supported (if any) by the file. If two or more
+modules are linked together their garbage collection metadata needs to
+be merged rather than appended together.
+
+The Objective-C garbage collection module flags metadata consists of the
+following key-value pairs:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Key
+ - Value
+
+ * - ``Objective-C Version``
+ - **[Required]** — The Objective-C ABI version. Valid values are 1 and 2.
+
+ * - ``Objective-C Image Info Version``
+ - **[Required]** — The version of the image info section. Currently
+ always 0.
+
+ * - ``Objective-C Image Info Section``
+ - **[Required]** — The section to place the metadata. Valid values are
+ ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and
+ ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for
+ Objective-C ABI version 2.
+
+ * - ``Objective-C Garbage Collection``
+ - **[Required]** — Specifies whether garbage collection is supported or
+ not. Valid values are 0, for no garbage collection, and 2, for garbage
+ collection supported.
+
+ * - ``Objective-C GC Only``
+ - **[Optional]** — Specifies that only garbage collection is supported.
+ If present, its value must be 6. This flag requires that the
+ ``Objective-C Garbage Collection`` flag have the value 2.
+
+Some important flag interactions:
+
+- If a module with ``Objective-C Garbage Collection`` set to 0 is
+ merged with a module with ``Objective-C Garbage Collection`` set to
+ 2, then the resulting module has the
+ ``Objective-C Garbage Collection`` flag set to 0.
+- A module with ``Objective-C Garbage Collection`` set to 0 cannot be
+ merged with a module with ``Objective-C GC Only`` set to 6.
+
+Intrinsic Global Variables
+==========================
+
+LLVM has a number of "magic" global variables that contain data that
+affect code generation or other IR semantics. These are documented here.
+All globals of this sort should have a section specified as
+"``llvm.metadata``". This section and all globals that start with
+"``llvm.``" are reserved for use by LLVM.
+
+The '``llvm.used``' Global Variable
+-----------------------------------
+
+The ``@llvm.used`` global is an array with i8\* element type which has
+:ref:`appending linkage <linkage_appending>`. This array contains a list of
+pointers to global variables and functions which may optionally have a
+pointer cast formed of bitcast or getelementptr. For example, a legal
+use of it is:
+
+.. code-block:: llvm
+
+ @X = global i8 4
+ @Y = global i32 123
+
+ @llvm.used = appending global [2 x i8*] [
+ i8* @X,
+ i8* bitcast (i32* @Y to i8*)
+ ], section "llvm.metadata"
+
+If a global variable appears in the ``@llvm.used`` list, then the
+compiler, assembler, and linker are required to treat the symbol as if
+there is a reference to the global that it cannot see. For example, if a
+variable has internal linkage and no references other than that from the
+``@llvm.used`` list, it cannot be deleted. This is commonly used to
+represent references from inline asms and other things the compiler
+cannot "see", and corresponds to "``attribute((used))``" in GNU C.
+
+On some targets, the code generator must emit a directive to the
+assembler or object file to prevent the assembler and linker from
+molesting the symbol.
+
+The '``llvm.compiler.used``' Global Variable
+--------------------------------------------
+
+The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used``
+directive, except that it only prevents the compiler from touching the
+symbol. On targets that support it, this allows an intelligent linker to
+optimize references to the symbol without being impeded as it would be
+by ``@llvm.used``.
+
+This is a rare construct that should only be used in rare circumstances,
+and should not be exposed to source languages.
+
+The '``llvm.global_ctors``' Global Variable
+-------------------------------------------
+
+.. code-block:: llvm
+
+ %0 = type { i32, void ()* }
+ @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
+
+The ``@llvm.global_ctors`` array contains a list of constructor
+functions and associated priorities. The functions referenced by this
+array will be called in ascending order of priority (i.e. lowest first)
+when the module is loaded. The order of functions with the same priority
+is not defined.
+
+The '``llvm.global_dtors``' Global Variable
+-------------------------------------------
+
+.. code-block:: llvm
+
+ %0 = type { i32, void ()* }
+ @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
+
+The ``@llvm.global_dtors`` array contains a list of destructor functions
+and associated priorities. The functions referenced by this array will
+be called in descending order of priority (i.e. highest first) when the
+module is loaded. The order of functions with the same priority is not
+defined.
+
+Instruction Reference
+=====================
+
+The LLVM instruction set consists of several different classifications
+of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
+instructions <binaryops>`, :ref:`bitwise binary
+instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
+:ref:`other instructions <otherops>`.
+
+.. _terminators:
+
+Terminator Instructions
+-----------------------
+
+As mentioned :ref:`previously <functionstructure>`, every basic block in a
+program ends with a "Terminator" instruction, which indicates which
+block should be executed after the current block is finished. These
+terminator instructions typically yield a '``void``' value: they produce
+control flow, not values (the one exception being the
+':ref:`invoke <i_invoke>`' instruction).
+
+The terminator instructions are: ':ref:`ret <i_ret>`',
+':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
+':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
+':ref:`resume <i_resume>`', and ':ref:`unreachable <i_unreachable>`'.
+
+.. _i_ret:
+
+'``ret``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ ret <type> <value> ; Return a value from a non-void function
+ ret void ; Return from void function
+
+Overview:
+"""""""""
+
+The '``ret``' instruction is used to return control flow (and optionally
+a value) from a function back to the caller.
+
+There are two forms of the '``ret``' instruction: one that returns a
+value and then causes control flow, and one that just causes control
+flow to occur.
+
+Arguments:
+""""""""""
+
+The '``ret``' instruction optionally accepts a single argument, the
+return value. The type of the return value must be a ':ref:`first
+class <t_firstclass>`' type.
+
+A function is not :ref:`well formed <wellformed>` if it it has a non-void
+return type and contains a '``ret``' instruction with no return value or
+a return value with a type that does not match its type, or if it has a
+void return type and contains a '``ret``' instruction with a return
+value.
+
+Semantics:
+""""""""""
+
+When the '``ret``' instruction is executed, control flow returns back to
+the calling function's context. If the caller is a
+":ref:`call <i_call>`" instruction, execution continues at the
+instruction after the call. If the caller was an
+":ref:`invoke <i_invoke>`" instruction, execution continues at the
+beginning of the "normal" destination block. If the instruction returns
+a value, that value shall set the call or invoke instruction's return
+value.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ret i32 5 ; Return an integer value of 5
+ ret void ; Return from a void function
+ ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
+
+.. _i_br:
+
+'``br``' Instruction
+^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ br i1 <cond>, label <iftrue>, label <iffalse>
+ br label <dest> ; Unconditional branch
+
+Overview:
+"""""""""
+
+The '``br``' instruction is used to cause control flow to transfer to a
+different basic block in the current function. There are two forms of
+this instruction, corresponding to a conditional branch and an
+unconditional branch.
+
+Arguments:
+""""""""""
+
+The conditional branch form of the '``br``' instruction takes a single
+'``i1``' value and two '``label``' values. The unconditional form of the
+'``br``' instruction takes a single '``label``' value as a target.
+
+Semantics:
+""""""""""
+
+Upon execution of a conditional '``br``' instruction, the '``i1``'
+argument is evaluated. If the value is ``true``, control flows to the
+'``iftrue``' ``label`` argument. If "cond" is ``false``, control flows
+to the '``iffalse``' ``label`` argument.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ Test:
+ %cond = icmp eq i32 %a, %b
+ br i1 %cond, label %IfEqual, label %IfUnequal
+ IfEqual:
+ ret i32 1
+ IfUnequal:
+ ret i32 0
+
+.. _i_switch:
+
+'``switch``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
+
+Overview:
+"""""""""
+
+The '``switch``' instruction is used to transfer control flow to one of
+several different places. It is a generalization of the '``br``'
+instruction, allowing a branch to occur to one of many possible
+destinations.
+
+Arguments:
+""""""""""
+
+The '``switch``' instruction uses three parameters: an integer
+comparison value '``value``', a default '``label``' destination, and an
+array of pairs of comparison value constants and '``label``'s. The table
+is not allowed to contain duplicate constant entries.
+
+Semantics:
+""""""""""
+
+The ``switch`` instruction specifies a table of values and destinations.
+When the '``switch``' instruction is executed, this table is searched
+for the given value. If the value is found, control flow is transferred
+to the corresponding destination; otherwise, control flow is transferred
+to the default destination.
+
+Implementation:
+"""""""""""""""
+
+Depending on properties of the target machine and the particular
+``switch`` instruction, this instruction may be code generated in
+different ways. For example, it could be generated as a series of
+chained conditional branches or with a lookup table.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ; Emulate a conditional br instruction
+ %Val = zext i1 %value to i32
+ switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
+
+ ; Emulate an unconditional br instruction
+ switch i32 0, label %dest [ ]
+
+ ; Implement a jump table:
+ switch i32 %val, label %otherwise [ i32 0, label %onzero
+ i32 1, label %onone
+ i32 2, label %ontwo ]
+
+.. _i_indirectbr:
+
+'``indirectbr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
+
+Overview:
+"""""""""
+
+The '``indirectbr``' instruction implements an indirect branch to a
+label within the current function, whose address is specified by
+"``address``". Address must be derived from a
+:ref:`blockaddress <blockaddress>` constant.
+
+Arguments:
+""""""""""
+
+The '``address``' argument is the address of the label to jump to. The
+rest of the arguments indicate the full set of possible destinations
+that the address may point to. Blocks are allowed to occur multiple
+times in the destination list, though this isn't particularly useful.
+
+This destination list is required so that dataflow analysis has an
+accurate understanding of the CFG.
+
+Semantics:
+""""""""""
+
+Control transfers to the block specified in the address argument. All
+possible destination blocks must be listed in the label list, otherwise
+this instruction has undefined behavior. This implies that jumps to
+labels defined in other functions have undefined behavior as well.
+
+Implementation:
+"""""""""""""""
+
+This is typically implemented with a jump through a register.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
+
+.. _i_invoke:
+
+'``invoke``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs]
+ to label <normal label> unwind label <exception label>
+
+Overview:
+"""""""""
+
+The '``invoke``' instruction causes control to transfer to a specified
+function, with the possibility of control flow transfer to either the
+'``normal``' label or the '``exception``' label. If the callee function
+returns with the "``ret``" instruction, control flow will return to the
+"normal" label. If the callee (or any indirect callees) returns via the
+":ref:`resume <i_resume>`" instruction or other exception handling
+mechanism, control is interrupted and continued at the dynamically
+nearest "exception" label.
+
+The '``exception``' label is a `landing
+pad <ExceptionHandling.html#overview>`_ for the exception. As such,
+'``exception``' label is required to have the
+":ref:`landingpad <i_landingpad>`" instruction, which contains the
+information about the behavior of the program after unwinding happens,
+as its first non-PHI instruction. The restrictions on the
+"``landingpad``" instruction's tightly couples it to the "``invoke``"
+instruction, so that the important information contained within the
+"``landingpad``" instruction can't be lost through normal code motion.
+
+Arguments:
+""""""""""
+
+This instruction requires several arguments:
+
+#. The optional "cconv" marker indicates which :ref:`calling
+ convention <callingconv>` the call should use. If none is
+ specified, the call defaults to using C calling conventions.
+#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
+ values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
+ are valid here.
+#. '``ptr to function ty``': shall be the signature of the pointer to
+ function value being invoked. In most cases, this is a direct
+ function invocation, but indirect ``invoke``'s are just as possible,
+ branching off an arbitrary pointer to function value.
+#. '``function ptr val``': An LLVM value containing a pointer to a
+ function to be invoked.
+#. '``function args``': argument list whose types match the function
+ signature argument types and parameter attributes. All arguments must
+ be of :ref:`first class <t_firstclass>` type. If the function signature
+ indicates the function accepts a variable number of arguments, the
+ extra arguments can be specified.
+#. '``normal label``': the label reached when the called function
+ executes a '``ret``' instruction.
+#. '``exception label``': the label reached when a callee returns via
+ the :ref:`resume <i_resume>` instruction or other exception handling
+ mechanism.
+#. The optional :ref:`function attributes <fnattrs>` list. Only
+ '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
+ attributes are valid here.
+
+Semantics:
+""""""""""
+
+This instruction is designed to operate as a standard '``call``'
+instruction in most regards. The primary difference is that it
+establishes an association with a label, which is used by the runtime
+library to unwind the stack.
+
+This instruction is used in languages with destructors to ensure that
+proper cleanup is performed in the case of either a ``longjmp`` or a
+thrown exception. Additionally, this is important for implementation of
+'``catch``' clauses in high-level languages that support them.
+
+For the purposes of the SSA form, the definition of the value returned
+by the '``invoke``' instruction is deemed to occur on the edge from the
+current block to the "normal" label. If the callee unwinds then no
+return value is available.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %retval = invoke i32 @Test(i32 15) to label %Continue
+ unwind label %TestCleanup ; {i32}:retval set
+ %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
+ unwind label %TestCleanup ; {i32}:retval set
+
+.. _i_resume:
+
+'``resume``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ resume <type> <value>
+
+Overview:
+"""""""""
+
+The '``resume``' instruction is a terminator instruction that has no
+successors.
+
+Arguments:
+""""""""""
+
+The '``resume``' instruction requires one argument, which must have the
+same type as the result of any '``landingpad``' instruction in the same
+function.
+
+Semantics:
+""""""""""
+
+The '``resume``' instruction resumes propagation of an existing
+(in-flight) exception whose unwinding was interrupted with a
+:ref:`landingpad <i_landingpad>` instruction.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ resume { i8*, i32 } %exn
+
+.. _i_unreachable:
+
+'``unreachable``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ unreachable
+
+Overview:
+"""""""""
+
+The '``unreachable``' instruction has no defined semantics. This
+instruction is used to inform the optimizer that a particular portion of
+the code is not reachable. This can be used to indicate that the code
+after a no-return function cannot be reached, and other facts.
+
+Semantics:
+""""""""""
+
+The '``unreachable``' instruction has no defined semantics.
+
+.. _binaryops:
+
+Binary Operations
+-----------------
+
+Binary operators are used to do most of the computation in a program.
+They require two operands of the same type, execute an operation on
+them, and produce a single value. The operands might represent multiple
+data, as is the case with the :ref:`vector <t_vector>` data type. The
+result value has the same type as its operands.
+
+There are several different binary operators:
+
+.. _i_add:
+
+'``add``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = add <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = add nuw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = add nsw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = add nuw nsw <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``add``' instruction returns the sum of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``add``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the integer sum of the two operands.
+
+If the sum has unsigned overflow, the result returned is the
+mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
+the result.
+
+Because LLVM integers use a two's complement representation, this
+instruction is appropriate for both signed and unsigned integers.
+
+``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
+respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
+result value of the ``add`` is a :ref:`poison value <poisonvalues>` if
+unsigned and/or signed overflow, respectively, occurs.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = add i32 4, %var ; yields {i32}:result = 4 + %var
+
+.. _i_fadd:
+
+'``fadd``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``fadd``' instruction returns the sum of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fadd``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point sum of the two operands. This
+instruction can also take any number of :ref:`fast-math flags <fastmath>`,
+which are optimization hints to enable otherwise unsafe floating point
+optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fadd float 4.0, %var ; yields {float}:result = 4.0 + %var
+
+'``sub``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sub <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = sub nuw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = sub nsw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = sub nuw nsw <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``sub``' instruction returns the difference of its two operands.
+
+Note that the '``sub``' instruction is used to represent the '``neg``'
+instruction present in most other intermediate representations.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``sub``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the integer difference of the two operands.
+
+If the difference has unsigned overflow, the result returned is the
+mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
+the result.
+
+Because LLVM integers use a two's complement representation, this
+instruction is appropriate for both signed and unsigned integers.
+
+``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
+respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
+result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if
+unsigned and/or signed overflow, respectively, occurs.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = sub i32 4, %var ; yields {i32}:result = 4 - %var
+ <result> = sub i32 0, %val ; yields {i32}:result = -%var
+
+.. _i_fsub:
+
+'``fsub``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``fsub``' instruction returns the difference of its two operands.
+
+Note that the '``fsub``' instruction is used to represent the '``fneg``'
+instruction present in most other intermediate representations.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fsub``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point difference of the two operands.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fsub float 4.0, %var ; yields {float}:result = 4.0 - %var
+ <result> = fsub float -0.0, %val ; yields {float}:result = -%var
+
+'``mul``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = mul <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = mul nuw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = mul nsw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = mul nuw nsw <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``mul``' instruction returns the product of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``mul``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the integer product of the two operands.
+
+If the result of the multiplication has unsigned overflow, the result
+returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the
+bit width of the result.
+
+Because LLVM integers use a two's complement representation, and the
+result is the same width as the operands, this instruction returns the
+correct result for both signed and unsigned integers. If a full product
+(e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be
+sign-extended or zero-extended as appropriate to the width of the full
+product.
+
+``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
+respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
+result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if
+unsigned and/or signed overflow, respectively, occurs.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = mul i32 4, %var ; yields {i32}:result = 4 * %var
+
+.. _i_fmul:
+
+'``fmul``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``fmul``' instruction returns the product of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fmul``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point product of the two operands.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fmul float 4.0, %var ; yields {float}:result = 4.0 * %var
+
+'``udiv``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = udiv <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = udiv exact <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``udiv``' instruction returns the quotient of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``udiv``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the unsigned integer quotient of the two operands.
+
+Note that unsigned integer division and signed integer division are
+distinct operations; for signed integer division, use '``sdiv``'.
+
+Division by zero leads to undefined behavior.
+
+If the ``exact`` keyword is present, the result value of the ``udiv`` is
+a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as
+such, "((a udiv exact b) mul b) == a").
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = udiv i32 4, %var ; yields {i32}:result = 4 / %var
+
+'``sdiv``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sdiv <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = sdiv exact <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``sdiv``' instruction returns the quotient of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``sdiv``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the signed integer quotient of the two operands
+rounded towards zero.
+
+Note that signed integer division and unsigned integer division are
+distinct operations; for unsigned integer division, use '``udiv``'.
+
+Division by zero leads to undefined behavior. Overflow also leads to
+undefined behavior; this is a rare case, but can occur, for example, by
+doing a 32-bit division of -2147483648 by -1.
+
+If the ``exact`` keyword is present, the result value of the ``sdiv`` is
+a :ref:`poison value <poisonvalues>` if the result would be rounded.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = sdiv i32 4, %var ; yields {i32}:result = 4 / %var
+
+.. _i_fdiv:
+
+'``fdiv``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``fdiv``' instruction returns the quotient of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fdiv``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point quotient of the two operands.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fdiv float 4.0, %var ; yields {float}:result = 4.0 / %var
+
+'``urem``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = urem <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``urem``' instruction returns the remainder from the unsigned
+division of its two arguments.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``urem``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+This instruction returns the unsigned integer *remainder* of a division.
+This instruction always performs an unsigned division to get the
+remainder.
+
+Note that unsigned integer remainder and signed integer remainder are
+distinct operations; for signed integer remainder, use '``srem``'.
+
+Taking the remainder of a division by zero leads to undefined behavior.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = urem i32 4, %var ; yields {i32}:result = 4 % %var
+
+'``srem``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = srem <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``srem``' instruction returns the remainder from the signed
+division of its two operands. This instruction can also take
+:ref:`vector <t_vector>` versions of the values in which case the elements
+must be integers.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``srem``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+This instruction returns the *remainder* of a division (where the result
+is either zero or has the same sign as the dividend, ``op1``), not the
+*modulo* operator (where the result is either zero or has the same sign
+as the divisor, ``op2``) of a value. For more information about the
+difference, see `The Math
+Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a
+table of how this is implemented in various languages, please see
+`Wikipedia: modulo
+operation <http://en.wikipedia.org/wiki/Modulo_operation>`_.
+
+Note that signed integer remainder and unsigned integer remainder are
+distinct operations; for unsigned integer remainder, use '``urem``'.
+
+Taking the remainder of a division by zero leads to undefined behavior.
+Overflow also leads to undefined behavior; this is a rare case, but can
+occur, for example, by taking the remainder of a 32-bit division of
+-2147483648 by -1. (The remainder doesn't actually overflow, but this
+rule lets srem be implemented using instructions that return both the
+result of the division and the remainder.)
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = srem i32 4, %var ; yields {i32}:result = 4 % %var
+
+.. _i_frem:
+
+'``frem``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``frem``' instruction returns the remainder from the division of
+its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``frem``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+This instruction returns the *remainder* of a division. The remainder
+has the same sign as the dividend. This instruction can also take any
+number of :ref:`fast-math flags <fastmath>`, which are optimization hints
+to enable otherwise unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = frem float 4.0, %var ; yields {float}:result = 4.0 % %var
+
+.. _bitwiseops:
+
+Bitwise Binary Operations
+-------------------------
+
+Bitwise binary operators are used to do various forms of bit-twiddling
+in a program. They are generally very efficient instructions and can
+commonly be strength reduced from other instructions. They require two
+operands of the same type, execute an operation on them, and produce a
+single value. The resulting value is the same type as its operands.
+
+'``shl``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = shl <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = shl nuw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = shl nsw <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = shl nuw nsw <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``shl``' instruction returns the first operand shifted to the left
+a specified number of bits.
+
+Arguments:
+""""""""""
+
+Both arguments to the '``shl``' instruction must be the same
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
+'``op2``' is treated as an unsigned value.
+
+Semantics:
+""""""""""
+
+The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`,
+where ``n`` is the width of the result. If ``op2`` is (statically or
+dynamically) negative or equal to or larger than the number of bits in
+``op1``, the result is undefined. If the arguments are vectors, each
+vector element of ``op1`` is shifted by the corresponding shift amount
+in ``op2``.
+
+If the ``nuw`` keyword is present, then the shift produces a :ref:`poison
+value <poisonvalues>` if it shifts out any non-zero bits. If the
+``nsw`` keyword is present, then the shift produces a :ref:`poison
+value <poisonvalues>` if it shifts out any bits that disagree with the
+resultant sign bit. As such, NUW/NSW have the same semantics as they
+would if the shift were expressed as a mul instruction with the same
+nsw/nuw bits in (mul %op1, (shl 1, %op2)).
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = shl i32 4, %var ; yields {i32}: 4 << %var
+ <result> = shl i32 4, 2 ; yields {i32}: 16
+ <result> = shl i32 1, 10 ; yields {i32}: 1024
+ <result> = shl i32 1, 32 ; undefined
+ <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4>
+
+'``lshr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = lshr <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = lshr exact <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``lshr``' instruction (logical shift right) returns the first
+operand shifted to the right a specified number of bits with zero fill.
+
+Arguments:
+""""""""""
+
+Both arguments to the '``lshr``' instruction must be the same
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
+'``op2``' is treated as an unsigned value.
+
+Semantics:
+""""""""""
+
+This instruction always performs a logical shift right operation. The
+most significant bits of the result will be filled with zero bits after
+the shift. If ``op2`` is (statically or dynamically) equal to or larger
+than the number of bits in ``op1``, the result is undefined. If the
+arguments are vectors, each vector element of ``op1`` is shifted by the
+corresponding shift amount in ``op2``.
+
+If the ``exact`` keyword is present, the result value of the ``lshr`` is
+a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
+non-zero.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = lshr i32 4, 1 ; yields {i32}:result = 2
+ <result> = lshr i32 4, 2 ; yields {i32}:result = 1
+ <result> = lshr i8 4, 3 ; yields {i8}:result = 0
+ <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7FFFFFFF
+ <result> = lshr i32 1, 32 ; undefined
+ <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
+
+'``ashr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = ashr <ty> <op1>, <op2> ; yields {ty}:result
+ <result> = ashr exact <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``ashr``' instruction (arithmetic shift right) returns the first
+operand shifted to the right a specified number of bits with sign
+extension.
+
+Arguments:
+""""""""""
+
+Both arguments to the '``ashr``' instruction must be the same
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
+'``op2``' is treated as an unsigned value.
+
+Semantics:
+""""""""""
+
+This instruction always performs an arithmetic shift right operation,
+The most significant bits of the result will be filled with the sign bit
+of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger
+than the number of bits in ``op1``, the result is undefined. If the
+arguments are vectors, each vector element of ``op1`` is shifted by the
+corresponding shift amount in ``op2``.
+
+If the ``exact`` keyword is present, the result value of the ``ashr`` is
+a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
+non-zero.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = ashr i32 4, 1 ; yields {i32}:result = 2
+ <result> = ashr i32 4, 2 ; yields {i32}:result = 1
+ <result> = ashr i8 4, 3 ; yields {i8}:result = 0
+ <result> = ashr i8 -2, 1 ; yields {i8}:result = -1
+ <result> = ashr i32 1, 32 ; undefined
+ <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0>
+
+'``and``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = and <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``and``' instruction returns the bitwise logical and of its two
+operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``and``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The truth table used for the '``and``' instruction is:
+
++-----+-----+-----+
+| In0 | In1 | Out |
++-----+-----+-----+
+| 0 | 0 | 0 |
++-----+-----+-----+
+| 0 | 1 | 0 |
++-----+-----+-----+
+| 1 | 0 | 0 |
++-----+-----+-----+
+| 1 | 1 | 1 |
++-----+-----+-----+
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = and i32 4, %var ; yields {i32}:result = 4 & %var
+ <result> = and i32 15, 40 ; yields {i32}:result = 8
+ <result> = and i32 4, 8 ; yields {i32}:result = 0
+
+'``or``' Instruction
+^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = or <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``or``' instruction returns the bitwise logical inclusive or of its
+two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``or``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The truth table used for the '``or``' instruction is:
+
++-----+-----+-----+
+| In0 | In1 | Out |
++-----+-----+-----+
+| 0 | 0 | 0 |
++-----+-----+-----+
+| 0 | 1 | 1 |
++-----+-----+-----+
+| 1 | 0 | 1 |
++-----+-----+-----+
+| 1 | 1 | 1 |
++-----+-----+-----+
+
+Example:
+""""""""
+
+::
+
+ <result> = or i32 4, %var ; yields {i32}:result = 4 | %var
+ <result> = or i32 15, 40 ; yields {i32}:result = 47
+ <result> = or i32 4, 8 ; yields {i32}:result = 12
+
+'``xor``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = xor <ty> <op1>, <op2> ; yields {ty}:result
+
+Overview:
+"""""""""
+
+The '``xor``' instruction returns the bitwise logical exclusive or of
+its two operands. The ``xor`` is used to implement the "one's
+complement" operation, which is the "~" operator in C.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``xor``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The truth table used for the '``xor``' instruction is:
+
++-----+-----+-----+
+| In0 | In1 | Out |
++-----+-----+-----+
+| 0 | 0 | 0 |
++-----+-----+-----+
+| 0 | 1 | 1 |
++-----+-----+-----+
+| 1 | 0 | 1 |
++-----+-----+-----+
+| 1 | 1 | 0 |
++-----+-----+-----+
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = xor i32 4, %var ; yields {i32}:result = 4 ^ %var
+ <result> = xor i32 15, 40 ; yields {i32}:result = 39
+ <result> = xor i32 4, 8 ; yields {i32}:result = 12
+ <result> = xor i32 %V, -1 ; yields {i32}:result = ~%V
+
+Vector Operations
+-----------------
+
+LLVM supports several instructions to represent vector operations in a
+target-independent manner. These instructions cover the element-access
+and vector-specific operations needed to process vectors effectively.
+While LLVM does directly support these vector operations, many
+sophisticated algorithms will want to use target-specific intrinsics to
+take full advantage of a specific target.
+
+.. _i_extractelement:
+
+'``extractelement``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = extractelement <n x <ty>> <val>, i32 <idx> ; yields <ty>
+
+Overview:
+"""""""""
+
+The '``extractelement``' instruction extracts a single scalar element
+from a vector at a specified index.
+
+Arguments:
+""""""""""
+
+The first operand of an '``extractelement``' instruction is a value of
+:ref:`vector <t_vector>` type. The second operand is an index indicating
+the position from which to extract the element. The index may be a
+variable.
+
+Semantics:
+""""""""""
+
+The result is a scalar of the same type as the element type of ``val``.
+Its value is the value at position ``idx`` of ``val``. If ``idx``
+exceeds the length of ``val``, the results are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32
+
+.. _i_insertelement:
+
+'``insertelement``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx> ; yields <n x <ty>>
+
+Overview:
+"""""""""
+
+The '``insertelement``' instruction inserts a scalar element into a
+vector at a specified index.
+
+Arguments:
+""""""""""
+
+The first operand of an '``insertelement``' instruction is a value of
+:ref:`vector <t_vector>` type. The second operand is a scalar value whose
+type must equal the element type of the first operand. The third operand
+is an index indicating the position at which to insert the value. The
+index may be a variable.
+
+Semantics:
+""""""""""
+
+The result is a vector of the same type as ``val``. Its element values
+are those of ``val`` except at position ``idx``, where it gets the value
+``elt``. If ``idx`` exceeds the length of ``val``, the results are
+undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32>
+
+.. _i_shufflevector:
+
+'``shufflevector``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>>
+
+Overview:
+"""""""""
+
+The '``shufflevector``' instruction constructs a permutation of elements
+from two input vectors, returning a vector with the same element type as
+the input and length that is the same as the shuffle mask.
+
+Arguments:
+""""""""""
+
+The first two operands of a '``shufflevector``' instruction are vectors
+with the same type. The third argument is a shuffle mask whose element
+type is always 'i32'. The result of the instruction is a vector whose
+length is the same as the shuffle mask and whose element type is the
+same as the element type of the first two operands.
+
+The shuffle mask operand is required to be a constant vector with either
+constant integer or undef values.
+
+Semantics:
+""""""""""
+
+The elements of the two input vectors are numbered from left to right
+across both of the vectors. The shuffle mask operand specifies, for each
+element of the result vector, which element of the two input vectors the
+result element gets. The element selector may be undef (meaning "don't
+care") and the second operand may be undef if performing a shuffle from
+only one vector.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32>
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
+ <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle.
+ <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
+ <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32>
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32>
+
+Aggregate Operations
+--------------------
+
+LLVM supports several instructions for working with
+:ref:`aggregate <t_aggregate>` values.
+
+.. _i_extractvalue:
+
+'``extractvalue``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
+
+Overview:
+"""""""""
+
+The '``extractvalue``' instruction extracts the value of a member field
+from an :ref:`aggregate <t_aggregate>` value.
+
+Arguments:
+""""""""""
+
+The first operand of an '``extractvalue``' instruction is a value of
+:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The operands are
+constant indices to specify which value to extract in a similar manner
+as indices in a '``getelementptr``' instruction.
+
+The major differences to ``getelementptr`` indexing are:
+
+- Since the value being indexed is not a pointer, the first index is
+ omitted and assumed to be zero.
+- At least one index must be specified.
+- Not only struct indices but also array indices must be in bounds.
+
+Semantics:
+""""""""""
+
+The result is the value at the position in the aggregate specified by
+the index operands.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = extractvalue {i32, float} %agg, 0 ; yields i32
+
+.. _i_insertvalue:
+
+'``insertvalue``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type>
+
+Overview:
+"""""""""
+
+The '``insertvalue``' instruction inserts a value into a member field in
+an :ref:`aggregate <t_aggregate>` value.
+
+Arguments:
+""""""""""
+
+The first operand of an '``insertvalue``' instruction is a value of
+:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The second operand is
+a first-class value to insert. The following operands are constant
+indices indicating the position at which to insert the value in a
+similar manner as indices in a '``extractvalue``' instruction. The value
+to insert must have the same type as the value identified by the
+indices.
+
+Semantics:
+""""""""""
+
+The result is an aggregate of the same type as ``val``. Its value is
+that of ``val`` except that the value at the position specified by the
+indices is that of ``elt``.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef}
+ %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val}
+ %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0 ; yields {i32 1, float %val}
+
+.. _memoryops:
+
+Memory Access and Addressing Operations
+---------------------------------------
+
+A key design point of an SSA-based representation is how it represents
+memory. In LLVM, no memory locations are in SSA form, which makes things
+very simple. This section describes how to read, write, and allocate
+memory in LLVM.
+
+.. _i_alloca:
+
+'``alloca``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = alloca <type>[, <ty> <NumElements>][, align <alignment>] ; yields {type*}:result
+
+Overview:
+"""""""""
+
+The '``alloca``' instruction allocates memory on the stack frame of the
+currently executing function, to be automatically released when this
+function returns to its caller. The object is always allocated in the
+generic address space (address space zero).
+
+Arguments:
+""""""""""
+
+The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements``
+bytes of memory on the runtime stack, returning a pointer of the
+appropriate type to the program. If "NumElements" is specified, it is
+the number of elements allocated, otherwise "NumElements" is defaulted
+to be one. If a constant alignment is specified, the value result of the
+allocation is guaranteed to be aligned to at least that boundary. If not
+specified, or if zero, the target can choose to align the allocation on
+any convenient boundary compatible with the type.
+
+'``type``' may be any sized type.
+
+Semantics:
+""""""""""
+
+Memory is allocated; a pointer is returned. The operation is undefined
+if there is insufficient stack space for the allocation. '``alloca``'d
+memory is automatically released when the function returns. The
+'``alloca``' instruction is commonly used to represent automatic
+variables that must have an address available. When the function returns
+(either with the ``ret`` or ``resume`` instructions), the memory is
+reclaimed. Allocating zero bytes is legal, but the result is undefined.
+The order in which memory is allocated (ie., which way the stack grows)
+is not specified.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %ptr = alloca i32 ; yields {i32*}:ptr
+ %ptr = alloca i32, i32 4 ; yields {i32*}:ptr
+ %ptr = alloca i32, i32 4, align 1024 ; yields {i32*}:ptr
+ %ptr = alloca i32, align 1024 ; yields {i32*}:ptr
+
+.. _i_load:
+
+'``load``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>]
+ <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
+ !<index> = !{ i32 1 }
+
+Overview:
+"""""""""
+
+The '``load``' instruction is used to read from memory.
+
+Arguments:
+""""""""""
+
+The argument to the '``load``' instruction specifies the memory address
+from which to load. The pointer must point to a :ref:`first
+class <t_firstclass>` type. If the ``load`` is marked as ``volatile``,
+then the optimizer is not allowed to modify the number or order of
+execution of this ``load`` with other :ref:`volatile
+operations <volatile>`.
+
+If the ``load`` is marked as ``atomic``, it takes an extra
+:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
+``release`` and ``acq_rel`` orderings are not valid on ``load``
+instructions. Atomic loads produce :ref:`defined <memmodel>` results
+when they may see multiple atomic stores. The type of the pointee must
+be an integer type whose bit width is a power of two greater than or
+equal to eight and less than or equal to a target-specific size limit.
+``align`` must be explicitly specified on atomic loads, and the load has
+undefined behavior if the alignment is not set to a value which is at
+least the size in bytes of the pointee. ``!nontemporal`` does not have
+any defined semantics for atomic loads.
+
+The optional constant ``align`` argument specifies the alignment of the
+operation (that is, the alignment of the memory address). A value of 0
+or an omitted ``align`` argument means that the operation has the abi
+alignment for the target. It is the responsibility of the code emitter
+to ensure that the alignment information is correct. Overestimating the
+alignment results in undefined behavior. Underestimating the alignment
+may produce less efficient code. An alignment of 1 is always safe.
+
+The optional ``!nontemporal`` metadata must reference a single
+metatadata name <index> corresponding to a metadata node with one
+``i32`` entry of value 1. The existence of the ``!nontemporal``
+metatadata on the instruction tells the optimizer and code generator
+that this load is not expected to be reused in the cache. The code
+generator may select special instructions to save cache bandwidth, such
+as the ``MOVNT`` instruction on x86.
+
+The optional ``!invariant.load`` metadata must reference a single
+metatadata name <index> corresponding to a metadata node with no
+entries. The existence of the ``!invariant.load`` metatadata on the
+instruction tells the optimizer and code generator that this load
+address points to memory which does not change value during program
+execution. The optimizer may then move this load around, for example, by
+hoisting it out of loops using loop invariant code motion.
+
+Semantics:
+""""""""""
+
+The location of memory pointed to is loaded. If the value being loaded
+is of scalar type then the number of bytes read does not exceed the
+minimum number of bytes needed to hold all bits of the type. For
+example, loading an ``i24`` reads at most three bytes. When loading a
+value of a type like ``i20`` with a size that is not an integral number
+of bytes, the result is undefined if the value was not originally
+written using a store of the same type.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %ptr = alloca i32 ; yields {i32*}:ptr
+ store i32 3, i32* %ptr ; yields {void}
+ %val = load i32* %ptr ; yields {i32}:val = i32 3
+
+.. _i_store:
+
+'``store``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] ; yields {void}
+ store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> ; yields {void}
+
+Overview:
+"""""""""
+
+The '``store``' instruction is used to write to memory.
+
+Arguments:
+""""""""""
+
+There are two arguments to the '``store``' instruction: a value to store
+and an address at which to store it. The type of the '``<pointer>``'
+operand must be a pointer to the :ref:`first class <t_firstclass>` type of
+the '``<value>``' operand. If the ``store`` is marked as ``volatile``,
+then the optimizer is not allowed to modify the number or order of
+execution of this ``store`` with other :ref:`volatile
+operations <volatile>`.
+
+If the ``store`` is marked as ``atomic``, it takes an extra
+:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
+``acquire`` and ``acq_rel`` orderings aren't valid on ``store``
+instructions. Atomic loads produce :ref:`defined <memmodel>` results
+when they may see multiple atomic stores. The type of the pointee must
+be an integer type whose bit width is a power of two greater than or
+equal to eight and less than or equal to a target-specific size limit.
+``align`` must be explicitly specified on atomic stores, and the store
+has undefined behavior if the alignment is not set to a value which is
+at least the size in bytes of the pointee. ``!nontemporal`` does not
+have any defined semantics for atomic stores.
+
+The optional constant "align" argument specifies the alignment of the
+operation (that is, the alignment of the memory address). A value of 0
+or an omitted "align" argument means that the operation has the abi
+alignment for the target. It is the responsibility of the code emitter
+to ensure that the alignment information is correct. Overestimating the
+alignment results in an undefined behavior. Underestimating the
+alignment may produce less efficient code. An alignment of 1 is always
+safe.
+
+The optional !nontemporal metadata must reference a single metatadata
+name <index> corresponding to a metadata node with one i32 entry of
+value 1. The existence of the !nontemporal metatadata on the instruction
+tells the optimizer and code generator that this load is not expected to
+be reused in the cache. The code generator may select special
+instructions to save cache bandwidth, such as the MOVNT instruction on
+x86.
+
+Semantics:
+""""""""""
+
+The contents of memory are updated to contain '``<value>``' at the
+location specified by the '``<pointer>``' operand. If '``<value>``' is
+of scalar type then the number of bytes written does not exceed the
+minimum number of bytes needed to hold all bits of the type. For
+example, storing an ``i24`` writes at most three bytes. When writing a
+value of a type like ``i20`` with a size that is not an integral number
+of bytes, it is unspecified what happens to the extra bits that do not
+belong to the type, but they will typically be overwritten.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %ptr = alloca i32 ; yields {i32*}:ptr
+ store i32 3, i32* %ptr ; yields {void}
+ %val = load i32* %ptr ; yields {i32}:val = i32 3
+
+.. _i_fence:
+
+'``fence``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ fence [singlethread] <ordering> ; yields {void}
+
+Overview:
+"""""""""
+
+The '``fence``' instruction is used to introduce happens-before edges
+between operations.
+
+Arguments:
+""""""""""
+
+'``fence``' instructions take an :ref:`ordering <ordering>` argument which
+defines what *synchronizes-with* edges they add. They can only be given
+``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings.
+
+Semantics:
+""""""""""
+
+A fence A which has (at least) ``release`` ordering semantics
+*synchronizes with* a fence B with (at least) ``acquire`` ordering
+semantics if and only if there exist atomic operations X and Y, both
+operating on some atomic object M, such that A is sequenced before X, X
+modifies M (either directly or through some side effect of a sequence
+headed by X), Y is sequenced before B, and Y observes M. This provides a
+*happens-before* dependency between A and B. Rather than an explicit
+``fence``, one (but not both) of the atomic operations X or Y might
+provide a ``release`` or ``acquire`` (resp.) ordering constraint and
+still *synchronize-with* the explicit ``fence`` and establish the
+*happens-before* edge.
+
+A ``fence`` which has ``seq_cst`` ordering, in addition to having both
+``acquire`` and ``release`` semantics specified above, participates in
+the global program order of other ``seq_cst`` operations and/or fences.
+
+The optional ":ref:`singlethread <singlethread>`" argument specifies
+that the fence only synchronizes with other fences in the same thread.
+(This is useful for interacting with signal handlers.)
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ fence acquire ; yields {void}
+ fence singlethread seq_cst ; yields {void}
+
+.. _i_cmpxchg:
+
+'``cmpxchg``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> ; yields {ty}
+
+Overview:
+"""""""""
+
+The '``cmpxchg``' instruction is used to atomically modify memory. It
+loads a value in memory and compares it to a given value. If they are
+equal, it stores a new value into the memory.
+
+Arguments:
+""""""""""
+
+There are three arguments to the '``cmpxchg``' instruction: an address
+to operate on, a value to compare to the value currently be at that
+address, and a new value to place at that address if the compared values
+are equal. The type of '<cmp>' must be an integer type whose bit width
+is a power of two greater than or equal to eight and less than or equal
+to a target-specific size limit. '<cmp>' and '<new>' must have the same
+type, and the type of '<pointer>' must be a pointer to that type. If the
+``cmpxchg`` is marked as ``volatile``, then the optimizer is not allowed
+to modify the number or order of execution of this ``cmpxchg`` with
+other :ref:`volatile operations <volatile>`.
+
+The :ref:`ordering <ordering>` argument specifies how this ``cmpxchg``
+synchronizes with other atomic operations.
+
+The optional "``singlethread``" argument declares that the ``cmpxchg``
+is only atomic with respect to code (usually signal handlers) running in
+the same thread as the ``cmpxchg``. Otherwise the cmpxchg is atomic with
+respect to all other code in the system.
+
+The pointer passed into cmpxchg must have alignment greater than or
+equal to the size in memory of the operand.
+
+Semantics:
+""""""""""
+
+The contents of memory at the location specified by the '``<pointer>``'
+operand is read and compared to '``<cmp>``'; if the read value is the
+equal, '``<new>``' is written. The original value at the location is
+returned.
+
+A successful ``cmpxchg`` is a read-modify-write instruction for the purpose
+of identifying release sequences. A failed ``cmpxchg`` is equivalent to an
+atomic load with an ordering parameter determined by dropping any
+``release`` part of the ``cmpxchg``'s ordering.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ entry:
+ %orig = atomic load i32* %ptr unordered ; yields {i32}
+ br label %loop
+
+ loop:
+ %cmp = phi i32 [ %orig, %entry ], [%old, %loop]
+ %squared = mul i32 %cmp, %cmp
+ %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared ; yields {i32}
+ %success = icmp eq i32 %cmp, %old
+ br i1 %success, label %done, label %loop
+
+ done:
+ ...
+
+.. _i_atomicrmw:
+
+'``atomicrmw``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> ; yields {ty}
+
+Overview:
+"""""""""
+
+The '``atomicrmw``' instruction is used to atomically modify memory.
+
+Arguments:
+""""""""""
+
+There are three arguments to the '``atomicrmw``' instruction: an
+operation to apply, an address whose value to modify, an argument to the
+operation. The operation must be one of the following keywords:
+
+- xchg
+- add
+- sub
+- and
+- nand
+- or
+- xor
+- max
+- min
+- umax
+- umin
+
+The type of '<value>' must be an integer type whose bit width is a power
+of two greater than or equal to eight and less than or equal to a
+target-specific size limit. The type of the '``<pointer>``' operand must
+be a pointer to that type. If the ``atomicrmw`` is marked as
+``volatile``, then the optimizer is not allowed to modify the number or
+order of execution of this ``atomicrmw`` with other :ref:`volatile
+operations <volatile>`.
+
+Semantics:
+""""""""""
+
+The contents of memory at the location specified by the '``<pointer>``'
+operand are atomically read, modified, and written back. The original
+value at the location is returned. The modification is specified by the
+operation argument:
+
+- xchg: ``*ptr = val``
+- add: ``*ptr = *ptr + val``
+- sub: ``*ptr = *ptr - val``
+- and: ``*ptr = *ptr & val``
+- nand: ``*ptr = ~(*ptr & val)``
+- or: ``*ptr = *ptr | val``
+- xor: ``*ptr = *ptr ^ val``
+- max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison)
+- min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison)
+- umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned
+ comparison)
+- umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned
+ comparison)
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %old = atomicrmw add i32* %ptr, i32 1 acquire ; yields {i32}
+
+.. _i_getelementptr:
+
+'``getelementptr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
+ <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}*
+ <result> = getelementptr <ptr vector> ptrval, <vector index type> idx
+
+Overview:
+"""""""""
+
+The '``getelementptr``' instruction is used to get the address of a
+subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs
+address calculation only and does not access memory.
+
+Arguments:
+""""""""""
+
+The first argument is always a pointer or a vector of pointers, and
+forms the basis of the calculation. The remaining arguments are indices
+that indicate which of the elements of the aggregate object are indexed.
+The interpretation of each index is dependent on the type being indexed
+into. The first index always indexes the pointer value given as the
+first argument, the second index indexes a value of the type pointed to
+(not necessarily the value directly pointed to, since the first index
+can be non-zero), etc. The first type indexed into must be a pointer
+value, subsequent types can be arrays, vectors, and structs. Note that
+subsequent types being indexed into can never be pointers, since that
+would require loading the pointer before continuing calculation.
+
+The type of each index argument depends on the type it is indexing into.
+When indexing into a (optionally packed) structure, only ``i32`` integer
+**constants** are allowed (when using a vector of indices they must all
+be the **same** ``i32`` integer constant). When indexing into an array,
+pointer or vector, integers of any width are allowed, and they are not
+required to be constant. These integers are treated as signed values
+where relevant.
+
+For example, let's consider a C code fragment and how it gets compiled
+to LLVM:
+
+.. code-block:: c
+
+ struct RT {
+ char A;
+ int B[10][20];
+ char C;
+ };
+ struct ST {
+ int X;
+ double Y;
+ struct RT Z;
+ };
+
+ int *foo(struct ST *s) {
+ return &s[1].Z.B[5][13];
+ }
+
+The LLVM code generated by Clang is:
+
+.. code-block:: llvm
+
+ %struct.RT = type { i8, [10 x [20 x i32]], i8 }
+ %struct.ST = type { i32, double, %struct.RT }
+
+ define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp {
+ entry:
+ %arrayidx = getelementptr inbounds %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13
+ ret i32* %arrayidx
+ }
+
+Semantics:
+""""""""""
+
+In the example above, the first index is indexing into the
+'``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``'
+= '``{ i32, double, %struct.RT }``' type, a structure. The second index
+indexes into the third element of the structure, yielding a
+'``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another
+structure. The third index indexes into the second element of the
+structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two
+dimensions of the array are subscripted into, yielding an '``i32``'
+type. The '``getelementptr``' instruction returns a pointer to this
+element, thus computing a value of '``i32*``' type.
+
+Note that it is perfectly legal to index partially through a structure,
+returning a pointer to an inner element. Because of this, the LLVM code
+for the given testcase is equivalent to:
+
+.. code-block:: llvm
+
+ define i32* @foo(%struct.ST* %s) {
+ %t1 = getelementptr %struct.ST* %s, i32 1 ; yields %struct.ST*:%t1
+ %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2 ; yields %struct.RT*:%t2
+ %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1 ; yields [10 x [20 x i32]]*:%t3
+ %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 ; yields [20 x i32]*:%t4
+ %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 ; yields i32*:%t5
+ ret i32* %t5
+ }
+
+If the ``inbounds`` keyword is present, the result value of the
+``getelementptr`` is a :ref:`poison value <poisonvalues>` if the base
+pointer is not an *in bounds* address of an allocated object, or if any
+of the addresses that would be formed by successive addition of the
+offsets implied by the indices to the base address with infinitely
+precise signed arithmetic are not an *in bounds* address of that
+allocated object. The *in bounds* addresses for an allocated object are
+all the addresses that point into the object, plus the address one byte
+past the end. In cases where the base is a vector of pointers the
+``inbounds`` keyword applies to each of the computations element-wise.
+
+If the ``inbounds`` keyword is not present, the offsets are added to the
+base address with silently-wrapping two's complement arithmetic. If the
+offsets have a different width from the pointer, they are sign-extended
+or truncated to the width of the pointer. The result value of the
+``getelementptr`` may be outside the object pointed to by the base
+pointer. The result value may not necessarily be used to access memory
+though, even if it happens to point into allocated storage. See the
+:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more
+information.
+
+The getelementptr instruction is often confusing. For some more insight
+into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ; yields [12 x i8]*:aptr
+ %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
+ ; yields i8*:vptr
+ %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1
+ ; yields i8*:eptr
+ %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
+ ; yields i32*:iptr
+ %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
+
+In cases where the pointer argument is a vector of pointers, each index
+must be a vector with the same number of elements. For example:
+
+.. code-block:: llvm
+
+ %A = getelementptr <4 x i8*> %ptrs, <4 x i64> %offsets,
+
+Conversion Operations
+---------------------
+
+The instructions in this category are the conversion instructions
+(casting) which all take a single operand and a type. They perform
+various bit conversions on the operand.
+
+'``trunc .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = trunc <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``trunc``' instruction truncates its operand to the type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``trunc``' instruction takes a value to trunc, and a type to trunc
+it to. Both types must be of :ref:`integer <t_integer>` types, or vectors
+of the same number of integers. The bit size of the ``value`` must be
+larger than the bit size of the destination type, ``ty2``. Equal sized
+types are not allowed.
+
+Semantics:
+""""""""""
+
+The '``trunc``' instruction truncates the high order bits in ``value``
+and converts the remaining bits to ``ty2``. Since the source size must
+be larger than the destination size, ``trunc`` cannot be a *no-op cast*.
+It will always truncate bits.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = trunc i32 257 to i8 ; yields i8:1
+ %Y = trunc i32 123 to i1 ; yields i1:true
+ %Z = trunc i32 122 to i1 ; yields i1:false
+ %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
+
+'``zext .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = zext <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``zext``' instruction zero extends its operand to type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``zext``' instruction takes a value to cast, and a type to cast it
+to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
+the same number of integers. The bit size of the ``value`` must be
+smaller than the bit size of the destination type, ``ty2``.
+
+Semantics:
+""""""""""
+
+The ``zext`` fills the high order bits of the ``value`` with zero bits
+until it reaches the size of the destination type, ``ty2``.
+
+When zero extending from i1, the result will always be either 0 or 1.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = zext i32 257 to i64 ; yields i64:257
+ %Y = zext i1 true to i32 ; yields i32:1
+ %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
+
+'``sext .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sext <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``sext``' sign extends ``value`` to the type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``sext``' instruction takes a value to cast, and a type to cast it
+to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
+the same number of integers. The bit size of the ``value`` must be
+smaller than the bit size of the destination type, ``ty2``.
+
+Semantics:
+""""""""""
+
+The '``sext``' instruction performs a sign extension by copying the sign
+bit (highest order bit) of the ``value`` until it reaches the bit size
+of the type ``ty2``.
+
+When sign extending from i1, the extension always results in -1 or 0.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = sext i8 -1 to i16 ; yields i16 :65535
+ %Y = sext i1 true to i32 ; yields i32:-1
+ %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
+
+'``fptrunc .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fptrunc <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fptrunc``' instruction truncates ``value`` to type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``fptrunc``' instruction takes a :ref:`floating point <t_floating>`
+value to cast and a :ref:`floating point <t_floating>` type to cast it to.
+The size of ``value`` must be larger than the size of ``ty2``. This
+implies that ``fptrunc`` cannot be used to make a *no-op cast*.
+
+Semantics:
+""""""""""
+
+The '``fptrunc``' instruction truncates a ``value`` from a larger
+:ref:`floating point <t_floating>` type to a smaller :ref:`floating
+point <t_floating>` type. If the value cannot fit within the
+destination type, ``ty2``, then the results are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fptrunc double 123.0 to float ; yields float:123.0
+ %Y = fptrunc double 1.0E+300 to float ; yields undefined
+
+'``fpext .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fpext <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fpext``' extends a floating point ``value`` to a larger floating
+point value.
+
+Arguments:
+""""""""""
+
+The '``fpext``' instruction takes a :ref:`floating point <t_floating>`
+``value`` to cast, and a :ref:`floating point <t_floating>` type to cast it
+to. The source type must be smaller than the destination type.
+
+Semantics:
+""""""""""
+
+The '``fpext``' instruction extends the ``value`` from a smaller
+:ref:`floating point <t_floating>` type to a larger :ref:`floating
+point <t_floating>` type. The ``fpext`` cannot be used to make a
+*no-op cast* because it always changes bits. Use ``bitcast`` to make a
+*no-op cast* for a floating point cast.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fpext float 3.125 to double ; yields double:3.125000e+00
+ %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000
+
+'``fptoui .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fptoui <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fptoui``' converts a floating point ``value`` to its unsigned
+integer equivalent of type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``fptoui``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`floating point <t_floating>` value, and a type to
+cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
+``ty`` is a vector floating point type, ``ty2`` must be a vector integer
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``fptoui``' instruction converts its :ref:`floating
+point <t_floating>` operand into the nearest (rounding towards zero)
+unsigned integer value. If the value cannot fit in ``ty2``, the results
+are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fptoui double 123.0 to i32 ; yields i32:123
+ %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1
+ %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1
+
+'``fptosi .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fptosi <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fptosi``' instruction converts :ref:`floating point <t_floating>`
+``value`` to type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``fptosi``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`floating point <t_floating>` value, and a type to
+cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
+``ty`` is a vector floating point type, ``ty2`` must be a vector integer
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``fptosi``' instruction converts its :ref:`floating
+point <t_floating>` operand into the nearest (rounding towards zero)
+signed integer value. If the value cannot fit in ``ty2``, the results
+are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fptosi double -123.0 to i32 ; yields i32:-123
+ %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1
+ %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1
+
+'``uitofp .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = uitofp <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``uitofp``' instruction regards ``value`` as an unsigned integer
+and converts that value to the ``ty2`` type.
+
+Arguments:
+""""""""""
+
+The '``uitofp``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
+``ty2``, which must be an :ref:`floating point <t_floating>` type. If
+``ty`` is a vector integer type, ``ty2`` must be a vector floating point
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``uitofp``' instruction interprets its operand as an unsigned
+integer quantity and converts it to the corresponding floating point
+value. If the value cannot fit in the floating point value, the results
+are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = uitofp i32 257 to float ; yields float:257.0
+ %Y = uitofp i8 -1 to double ; yields double:255.0
+
+'``sitofp .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sitofp <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``sitofp``' instruction regards ``value`` as a signed integer and
+converts that value to the ``ty2`` type.
+
+Arguments:
+""""""""""
+
+The '``sitofp``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
+``ty2``, which must be an :ref:`floating point <t_floating>` type. If
+``ty`` is a vector integer type, ``ty2`` must be a vector floating point
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``sitofp``' instruction interprets its operand as a signed integer
+quantity and converts it to the corresponding floating point value. If
+the value cannot fit in the floating point value, the results are
+undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = sitofp i32 257 to float ; yields float:257.0
+ %Y = sitofp i8 -1 to double ; yields double:-1.0
+
+.. _i_ptrtoint:
+
+'``ptrtoint .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``ptrtoint``' instruction converts the pointer or a vector of
+pointers ``value`` to the integer (or vector of integers) type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``ptrtoint``' instruction takes a ``value`` to cast, which must be
+a a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a
+type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or
+a vector of integers type.
+
+Semantics:
+""""""""""
+
+The '``ptrtoint``' instruction converts ``value`` to integer type
+``ty2`` by interpreting the pointer value as an integer and either
+truncating or zero extending that value to the size of the integer type.
+If ``value`` is smaller than ``ty2`` then a zero extension is done. If
+``value`` is larger than ``ty2`` then a truncation is done. If they are
+the same size, then nothing is done (*no-op cast*) other than a type
+change.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = ptrtoint i32* %P to i8 ; yields truncation on 32-bit architecture
+ %Y = ptrtoint i32* %P to i64 ; yields zero extension on 32-bit architecture
+ %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture
+
+.. _i_inttoptr:
+
+'``inttoptr .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = inttoptr <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``inttoptr``' instruction converts an integer ``value`` to a
+pointer type, ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to
+cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>`
+type.
+
+Semantics:
+""""""""""
+
+The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by
+applying either a zero extension or a truncation depending on the size
+of the integer ``value``. If ``value`` is larger than the size of a
+pointer then a truncation is done. If ``value`` is smaller than the size
+of a pointer then a zero extension is done. If they are the same size,
+nothing is done (*no-op cast*).
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = inttoptr i32 255 to i32* ; yields zero extension on 64-bit architecture
+ %Y = inttoptr i32 255 to i32* ; yields no-op on 32-bit architecture
+ %Z = inttoptr i64 0 to i32* ; yields truncation on 32-bit architecture
+ %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers
+
+.. _i_bitcast:
+
+'``bitcast .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = bitcast <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``bitcast``' instruction converts ``value`` to type ``ty2`` without
+changing any bits.
+
+Arguments:
+""""""""""
+
+The '``bitcast``' instruction takes a value to cast, which must be a
+non-aggregate first class value, and a type to cast it to, which must
+also be a non-aggregate :ref:`first class <t_firstclass>` type. The bit
+sizes of ``value`` and the destination type, ``ty2``, must be identical.
+If the source type is a pointer, the destination type must also be a
+pointer. This instruction supports bitwise conversion of vectors to
+integers and to vectors of other types (as long as they have the same
+size).
+
+Semantics:
+""""""""""
+
+The '``bitcast``' instruction converts ``value`` to type ``ty2``. It is
+always a *no-op cast* because no bits change with this conversion. The
+conversion is done as if the ``value`` had been stored to memory and
+read back as type ``ty2``. Pointer (or vector of pointers) types may
+only be converted to other pointer (or vector of pointers) types with
+this instruction. To convert pointers to other types, use the
+:ref:`inttoptr <i_inttoptr>` or :ref:`ptrtoint <i_ptrtoint>` instructions
+first.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = bitcast i8 255 to i8 ; yields i8 :-1
+ %Y = bitcast i32* %x to sint* ; yields sint*:%x
+ %Z = bitcast <2 x int> %V to i64; ; yields i64: %V
+ %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
+
+.. _otherops:
+
+Other Operations
+----------------
+
+The instructions in this category are the "miscellaneous" instructions,
+which defy better classification.
+
+.. _i_icmp:
+
+'``icmp``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = icmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:result
+
+Overview:
+"""""""""
+
+The '``icmp``' instruction returns a boolean value or a vector of
+boolean values based on comparison of its two integer, integer vector,
+pointer, or pointer vector operands.
+
+Arguments:
+""""""""""
+
+The '``icmp``' instruction takes three operands. The first operand is
+the condition code indicating the kind of comparison to perform. It is
+not a value, just a keyword. The possible condition code are:
+
+#. ``eq``: equal
+#. ``ne``: not equal
+#. ``ugt``: unsigned greater than
+#. ``uge``: unsigned greater or equal
+#. ``ult``: unsigned less than
+#. ``ule``: unsigned less or equal
+#. ``sgt``: signed greater than
+#. ``sge``: signed greater or equal
+#. ``slt``: signed less than
+#. ``sle``: signed less or equal
+
+The remaining two arguments must be :ref:`integer <t_integer>` or
+:ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They
+must also be identical types.
+
+Semantics:
+""""""""""
+
+The '``icmp``' compares ``op1`` and ``op2`` according to the condition
+code given as ``cond``. The comparison performed always yields either an
+:ref:`i1 <t_integer>` or vector of ``i1`` result, as follows:
+
+#. ``eq``: yields ``true`` if the operands are equal, ``false``
+ otherwise. No sign interpretation is necessary or performed.
+#. ``ne``: yields ``true`` if the operands are unequal, ``false``
+ otherwise. No sign interpretation is necessary or performed.
+#. ``ugt``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is greater than ``op2``.
+#. ``uge``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is greater than or equal to ``op2``.
+#. ``ult``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is less than ``op2``.
+#. ``ule``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is less than or equal to ``op2``.
+#. ``sgt``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is greater than ``op2``.
+#. ``sge``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is greater than or equal to ``op2``.
+#. ``slt``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is less than ``op2``.
+#. ``sle``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is less than or equal to ``op2``.
+
+If the operands are :ref:`pointer <t_pointer>` typed, the pointer values
+are compared as if they were integers.
+
+If the operands are integer vectors, then they are compared element by
+element. The result is an ``i1`` vector with the same number of elements
+as the values being compared. Otherwise, the result is an ``i1``.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = icmp eq i32 4, 5 ; yields: result=false
+ <result> = icmp ne float* %X, %X ; yields: result=false
+ <result> = icmp ult i16 4, 5 ; yields: result=true
+ <result> = icmp sgt i16 4, 5 ; yields: result=false
+ <result> = icmp ule i16 -4, 5 ; yields: result=false
+ <result> = icmp sge i16 4, 5 ; yields: result=false
+
+Note that the code generator does not yet support vector types with the
+``icmp`` instruction.
+
+.. _i_fcmp:
+
+'``fcmp``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fcmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:result
+
+Overview:
+"""""""""
+
+The '``fcmp``' instruction returns a boolean value or vector of boolean
+values based on comparison of its operands.
+
+If the operands are floating point scalars, then the result type is a
+boolean (:ref:`i1 <t_integer>`).
+
+If the operands are floating point vectors, then the result type is a
+vector of boolean with the same number of elements as the operands being
+compared.
+
+Arguments:
+""""""""""
+
+The '``fcmp``' instruction takes three operands. The first operand is
+the condition code indicating the kind of comparison to perform. It is
+not a value, just a keyword. The possible condition code are:
+
+#. ``false``: no comparison, always returns false
+#. ``oeq``: ordered and equal
+#. ``ogt``: ordered and greater than
+#. ``oge``: ordered and greater than or equal
+#. ``olt``: ordered and less than
+#. ``ole``: ordered and less than or equal
+#. ``one``: ordered and not equal
+#. ``ord``: ordered (no nans)
+#. ``ueq``: unordered or equal
+#. ``ugt``: unordered or greater than
+#. ``uge``: unordered or greater than or equal
+#. ``ult``: unordered or less than
+#. ``ule``: unordered or less than or equal
+#. ``une``: unordered or not equal
+#. ``uno``: unordered (either nans)
+#. ``true``: no comparison, always returns true
+
+*Ordered* means that neither operand is a QNAN while *unordered* means
+that either operand may be a QNAN.
+
+Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating
+point <t_floating>` type or a :ref:`vector <t_vector>` of floating point
+type. They must have identical types.
+
+Semantics:
+""""""""""
+
+The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the
+condition code given as ``cond``. If the operands are vectors, then the
+vectors are compared element by element. Each comparison performed
+always yields an :ref:`i1 <t_integer>` result, as follows:
+
+#. ``false``: always yields ``false``, regardless of operands.
+#. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is equal to ``op2``.
+#. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is greater than ``op2``.
+#. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is greater than or equal to ``op2``.
+#. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is less than ``op2``.
+#. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is less than or equal to ``op2``.
+#. ``one``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is not equal to ``op2``.
+#. ``ord``: yields ``true`` if both operands are not a QNAN.
+#. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ equal to ``op2``.
+#. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ greater than ``op2``.
+#. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ greater than or equal to ``op2``.
+#. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ less than ``op2``.
+#. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ less than or equal to ``op2``.
+#. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ not equal to ``op2``.
+#. ``uno``: yields ``true`` if either operand is a QNAN.
+#. ``true``: always yields ``true``, regardless of operands.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false
+ <result> = fcmp one float 4.0, 5.0 ; yields: result=true
+ <result> = fcmp olt float 4.0, 5.0 ; yields: result=true
+ <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false
+
+Note that the code generator does not yet support vector types with the
+``fcmp`` instruction.
+
+.. _i_phi:
+
+'``phi``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = phi <ty> [ <val0>, <label0>], ...
+
+Overview:
+"""""""""
+
+The '``phi``' instruction is used to implement the φ node in the SSA
+graph representing the function.
+
+Arguments:
+""""""""""
+
+The type of the incoming values is specified with the first type field.
+After this, the '``phi``' instruction takes a list of pairs as
+arguments, with one pair for each predecessor basic block of the current
+block. Only values of :ref:`first class <t_firstclass>` type may be used as
+the value arguments to the PHI node. Only labels may be used as the
+label arguments.
+
+There must be no non-phi instructions between the start of a basic block
+and the PHI instructions: i.e. PHI instructions must be first in a basic
+block.
+
+For the purposes of the SSA form, the use of each incoming value is
+deemed to occur on the edge from the corresponding predecessor block to
+the current block (but after any definition of an '``invoke``'
+instruction's return value on the same edge).
+
+Semantics:
+""""""""""
+
+At runtime, the '``phi``' instruction logically takes on the value
+specified by the pair corresponding to the predecessor basic block that
+executed just prior to the current block.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ Loop: ; Infinite loop that counts from 0 on up...
+ %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
+ %nextindvar = add i32 %indvar, 1
+ br label %Loop
+
+.. _i_select:
+
+'``select``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = select selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty
+
+ selty is either i1 or {<N x i1>}
+
+Overview:
+"""""""""
+
+The '``select``' instruction is used to choose one value based on a
+condition, without branching.
+
+Arguments:
+""""""""""
+
+The '``select``' instruction requires an 'i1' value or a vector of 'i1'
+values indicating the condition, and two values of the same :ref:`first
+class <t_firstclass>` type. If the val1/val2 are vectors and the
+condition is a scalar, then entire vectors are selected, not individual
+elements.
+
+Semantics:
+""""""""""
+
+If the condition is an i1 and it evaluates to 1, the instruction returns
+the first value argument; otherwise, it returns the second value
+argument.
+
+If the condition is a vector of i1, then the value arguments must be
+vectors of the same size, and the selection is done element by element.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = select i1 true, i8 17, i8 42 ; yields i8:17
+
+.. _i_call:
+
+'``call``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = [tail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
+
+Overview:
+"""""""""
+
+The '``call``' instruction represents a simple function call.
+
+Arguments:
+""""""""""
+
+This instruction requires several arguments:
+
+#. The optional "tail" marker indicates that the callee function does
+ not access any allocas or varargs in the caller. Note that calls may
+ be marked "tail" even if they do not occur before a
+ :ref:`ret <i_ret>` instruction. If the "tail" marker is present, the
+ function call is eligible for tail call optimization, but `might not
+ in fact be optimized into a jump <CodeGenerator.html#tailcallopt>`_.
+ The code generator may optimize calls marked "tail" with either 1)
+ automatic `sibling call
+ optimization <CodeGenerator.html#sibcallopt>`_ when the caller and
+ callee have matching signatures, or 2) forced tail call optimization
+ when the following extra requirements are met:
+
+ - Caller and callee both have the calling convention ``fastcc``.
+ - The call is in tail position (ret immediately follows call and ret
+ uses value of call or is void).
+ - Option ``-tailcallopt`` is enabled, or
+ ``llvm::GuaranteedTailCallOpt`` is ``true``.
+ - `Platform specific constraints are
+ met. <CodeGenerator.html#tailcallopt>`_
+
+#. The optional "cconv" marker indicates which :ref:`calling
+ convention <callingconv>` the call should use. If none is
+ specified, the call defaults to using C calling conventions. The
+ calling convention of the call must match the calling convention of
+ the target function, or else the behavior is undefined.
+#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
+ values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
+ are valid here.
+#. '``ty``': the type of the call instruction itself which is also the
+ type of the return value. Functions that return no value are marked
+ ``void``.
+#. '``fnty``': shall be the signature of the pointer to function value
+ being invoked. The argument types must match the types implied by
+ this signature. This type can be omitted if the function is not
+ varargs and if the function type does not return a pointer to a
+ function.
+#. '``fnptrval``': An LLVM value containing a pointer to a function to
+ be invoked. In most cases, this is a direct function invocation, but
+ indirect ``call``'s are just as possible, calling an arbitrary pointer
+ to function value.
+#. '``function args``': argument list whose types match the function
+ signature argument types and parameter attributes. All arguments must
+ be of :ref:`first class <t_firstclass>` type. If the function signature
+ indicates the function accepts a variable number of arguments, the
+ extra arguments can be specified.
+#. The optional :ref:`function attributes <fnattrs>` list. Only
+ '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
+ attributes are valid here.
+
+Semantics:
+""""""""""
+
+The '``call``' instruction is used to cause control flow to transfer to
+a specified function, with its incoming arguments bound to the specified
+values. Upon a '``ret``' instruction in the called function, control
+flow continues with the instruction after the function call, and the
+return value of the function is bound to the result argument.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %retval = call i32 @test(i32 %argc)
+ call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) ; yields i32
+ %X = tail call i32 @foo() ; yields i32
+ %Y = tail call fastcc i32 @foo() ; yields i32
+ call void %foo(i8 97 signext)
+
+ %struct.A = type { i32, i8 }
+ %r = call %struct.A @foo() ; yields { 32, i8 }
+ %gr = extractvalue %struct.A %r, 0 ; yields i32
+ %gr1 = extractvalue %struct.A %r, 1 ; yields i8
+ %Z = call void @foo() noreturn ; indicates that %foo never returns normally
+ %ZZ = call zeroext i32 @bar() ; Return value is %zero extended
+
+llvm treats calls to some functions with names and arguments that match
+the standard C99 library as being the C99 library functions, and may
+perform optimizations or generate code for them under that assumption.
+This is something we'd like to change in the future to provide better
+support for freestanding environments and non-C-based languages.
+
+.. _i_va_arg:
+
+'``va_arg``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <resultval> = va_arg <va_list*> <arglist>, <argty>
+
+Overview:
+"""""""""
+
+The '``va_arg``' instruction is used to access arguments passed through
+the "variable argument" area of a function call. It is used to implement
+the ``va_arg`` macro in C.
+
+Arguments:
+""""""""""
+
+This instruction takes a ``va_list*`` value and the type of the
+argument. It returns a value of the specified argument type and
+increments the ``va_list`` to point to the next argument. The actual
+type of ``va_list`` is target specific.
+
+Semantics:
+""""""""""
+
+The '``va_arg``' instruction loads an argument of the specified type
+from the specified ``va_list`` and causes the ``va_list`` to point to
+the next argument. For more information, see the variable argument
+handling :ref:`Intrinsic Functions <int_varargs>`.
+
+It is legal for this instruction to be called in a function which does
+not take a variable number of arguments, for example, the ``vfprintf``
+function.
+
+``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic
+function <intrinsics>` because it takes a type as an argument.
+
+Example:
+""""""""
+
+See the :ref:`variable argument processing <int_varargs>` section.
+
+Note that the code generator does not yet fully support va\_arg on many
+targets. Also, it does not currently support va\_arg with aggregate
+types on any target.
+
+.. _i_landingpad:
+
+'``landingpad``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+
+ <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>*
+
+ <clause> := catch <type> <value>
+ <clause> := filter <array constant type> <array constant>
+
+Overview:
+"""""""""
+
+The '``landingpad``' instruction is used by `LLVM's exception handling
+system <ExceptionHandling.html#overview>`_ to specify that a basic block
+is a landing pad — one where the exception lands, and corresponds to the
+code found in the ``catch`` portion of a ``try``/``catch`` sequence. It
+defines values supplied by the personality function (``pers_fn``) upon
+re-entry to the function. The ``resultval`` has the type ``resultty``.
+
+Arguments:
+""""""""""
+
+This instruction takes a ``pers_fn`` value. This is the personality
+function associated with the unwinding mechanism. The optional
+``cleanup`` flag indicates that the landing pad block is a cleanup.
+
+A ``clause`` begins with the clause type — ``catch`` or ``filter`` — and
+contains the global variable representing the "type" that may be caught
+or filtered respectively. Unlike the ``catch`` clause, the ``filter``
+clause takes an array constant as its argument. Use
+"``[0 x i8**] undef``" for a filter which cannot throw. The
+'``landingpad``' instruction must contain *at least* one ``clause`` or
+the ``cleanup`` flag.
+
+Semantics:
+""""""""""
+
+The '``landingpad``' instruction defines the values which are set by the
+personality function (``pers_fn``) upon re-entry to the function, and
+therefore the "result type" of the ``landingpad`` instruction. As with
+calling conventions, how the personality function results are
+represented in LLVM IR is target specific.
+
+The clauses are applied in order from top to bottom. If two
+``landingpad`` instructions are merged together through inlining, the
+clauses from the calling function are appended to the list of clauses.
+When the call stack is being unwound due to an exception being thrown,
+the exception is compared against each ``clause`` in turn. If it doesn't
+match any of the clauses, and the ``cleanup`` flag is not set, then
+unwinding continues further up the call stack.
+
+The ``landingpad`` instruction has several restrictions:
+
+- A landing pad block is a basic block which is the unwind destination
+ of an '``invoke``' instruction.
+- A landing pad block must have a '``landingpad``' instruction as its
+ first non-PHI instruction.
+- There can be only one '``landingpad``' instruction within the landing
+ pad block.
+- A basic block that is not a landing pad block may not include a
+ '``landingpad``' instruction.
+- All '``landingpad``' instructions in a function must have the same
+ personality function.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ;; A landing pad which can catch an integer.
+ %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+ catch i8** @_ZTIi
+ ;; A landing pad that is a cleanup.
+ %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+ cleanup
+ ;; A landing pad which can catch an integer and can only throw a double.
+ %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+ catch i8** @_ZTIi
+ filter [1 x i8**] [@_ZTId]
+
+.. _intrinsics:
+
+Intrinsic Functions
+===================
+
+LLVM supports the notion of an "intrinsic function". These functions
+have well known names and semantics and are required to follow certain
+restrictions. Overall, these intrinsics represent an extension mechanism
+for the LLVM language that does not require changing all of the
+transformations in LLVM when adding to the language (or the bitcode
+reader/writer, the parser, etc...).
+
+Intrinsic function names must all start with an "``llvm.``" prefix. This
+prefix is reserved in LLVM for intrinsic names; thus, function names may
+not begin with this prefix. Intrinsic functions must always be external
+functions: you cannot define the body of intrinsic functions. Intrinsic
+functions may only be used in call or invoke instructions: it is illegal
+to take the address of an intrinsic function. Additionally, because
+intrinsic functions are part of the LLVM language, it is required if any
+are added that they be documented here.
+
+Some intrinsic functions can be overloaded, i.e., the intrinsic
+represents a family of functions that perform the same operation but on
+different data types. Because LLVM can represent over 8 million
+different integer types, overloading is used commonly to allow an
+intrinsic function to operate on any integer type. One or more of the
+argument types or the result type can be overloaded to accept any
+integer type. Argument types may also be defined as exactly matching a
+previous argument's type or the result type. This allows an intrinsic
+function which accepts multiple arguments, but needs all of them to be
+of the same type, to only be overloaded with respect to a single
+argument or the result.
+
+Overloaded intrinsics will have the names of its overloaded argument
+types encoded into its function name, each preceded by a period. Only
+those types which are overloaded result in a name suffix. Arguments
+whose type is matched against another type do not. For example, the
+``llvm.ctpop`` function can take an integer of any width and returns an
+integer of exactly the same integer width. This leads to a family of
+functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and
+``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is
+overloaded, and only one type suffix is required. Because the argument's
+type is matched against the return type, it does not require its own
+name suffix.
+
+To learn how to add an intrinsic function, please see the `Extending
+LLVM Guide <ExtendingLLVM.html>`_.
+
+.. _int_varargs:
+
+Variable Argument Handling Intrinsics
+-------------------------------------
+
+Variable argument support is defined in LLVM with the
+:ref:`va_arg <i_va_arg>` instruction and these three intrinsic
+functions. These functions are related to the similarly named macros
+defined in the ``<stdarg.h>`` header file.
+
+All of these functions operate on arguments that use a target-specific
+value type "``va_list``". The LLVM assembly language reference manual
+does not define what this type is, so all transformations should be
+prepared to handle these functions regardless of the type used.
+
+This example shows how the :ref:`va_arg <i_va_arg>` instruction and the
+variable argument handling intrinsic functions are used.
+
+.. code-block:: llvm
+
+ define i32 @test(i32 %X, ...) {
+ ; Initialize variable argument processing
+ %ap = alloca i8*
+ %ap2 = bitcast i8** %ap to i8*
+ call void @llvm.va_start(i8* %ap2)
+
+ ; Read a single integer argument
+ %tmp = va_arg i8** %ap, i32
+
+ ; Demonstrate usage of llvm.va_copy and llvm.va_end
+ %aq = alloca i8*
+ %aq2 = bitcast i8** %aq to i8*
+ call void @llvm.va_copy(i8* %aq2, i8* %ap2)
+ call void @llvm.va_end(i8* %aq2)
+
+ ; Stop processing of arguments.
+ call void @llvm.va_end(i8* %ap2)
+ ret i32 %tmp
+ }
+
+ declare void @llvm.va_start(i8*)
+ declare void @llvm.va_copy(i8*, i8*)
+ declare void @llvm.va_end(i8*)
+
+.. _int_va_start:
+
+'``llvm.va_start``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void %llvm.va_start(i8* <arglist>)
+
+Overview:
+"""""""""
+
+The '``llvm.va_start``' intrinsic initializes ``*<arglist>`` for
+subsequent use by ``va_arg``.
+
+Arguments:
+""""""""""
+
+The argument is a pointer to a ``va_list`` element to initialize.
+
+Semantics:
+""""""""""
+
+The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro
+available in C. In a target-dependent way, it initializes the
+``va_list`` element to which the argument points, so that the next call
+to ``va_arg`` will produce the first variable argument passed to the
+function. Unlike the C ``va_start`` macro, this intrinsic does not need
+to know the last argument of the function as the compiler can figure
+that out.
+
+'``llvm.va_end``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.va_end(i8* <arglist>)
+
+Overview:
+"""""""""
+
+The '``llvm.va_end``' intrinsic destroys ``*<arglist>``, which has been
+initialized previously with ``llvm.va_start`` or ``llvm.va_copy``.
+
+Arguments:
+""""""""""
+
+The argument is a pointer to a ``va_list`` to destroy.
+
+Semantics:
+""""""""""
+
+The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro
+available in C. In a target-dependent way, it destroys the ``va_list``
+element to which the argument points. Calls to
+:ref:`llvm.va_start <int_va_start>` and
+:ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to
+``llvm.va_end``.
+
+.. _int_va_copy:
+
+'``llvm.va_copy``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
+
+Overview:
+"""""""""
+
+The '``llvm.va_copy``' intrinsic copies the current argument position
+from the source argument list to the destination argument list.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to a ``va_list`` element to initialize.
+The second argument is a pointer to a ``va_list`` element to copy from.
+
+Semantics:
+""""""""""
+
+The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro
+available in C. In a target-dependent way, it copies the source
+``va_list`` element into the destination ``va_list`` element. This
+intrinsic is necessary because the `` llvm.va_start`` intrinsic may be
+arbitrarily complex and require, for example, memory allocation.
+
+Accurate Garbage Collection Intrinsics
+--------------------------------------
+
+LLVM support for `Accurate Garbage Collection <GarbageCollection.html>`_
+(GC) requires the implementation and generation of these intrinsics.
+These intrinsics allow identification of :ref:`GC roots on the
+stack <int_gcroot>`, as well as garbage collector implementations that
+require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers.
+Front-ends for type-safe garbage collected languages should generate
+these intrinsics to make use of the LLVM garbage collectors. For more
+details, see `Accurate Garbage Collection with
+LLVM <GarbageCollection.html>`_.
+
+The garbage collection intrinsics only operate on objects in the generic
+address space (address space zero).
+
+.. _int_gcroot:
+
+'``llvm.gcroot``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+
+Overview:
+"""""""""
+
+The '``llvm.gcroot``' intrinsic declares the existence of a GC root to
+the code generator, and allows some metadata to be associated with it.
+
+Arguments:
+""""""""""
+
+The first argument specifies the address of a stack object that contains
+the root pointer. The second pointer (which must be either a constant or
+a global value address) contains the meta-data to be associated with the
+root.
+
+Semantics:
+""""""""""
+
+At runtime, a call to this intrinsic stores a null pointer into the
+"ptrloc" location. At compile-time, the code generator generates
+information to allow the runtime to find the pointer at GC safe points.
+The '``llvm.gcroot``' intrinsic may only be used in a function which
+:ref:`specifies a GC algorithm <gc>`.
+
+.. _int_gcread:
+
+'``llvm.gcread``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
+
+Overview:
+"""""""""
+
+The '``llvm.gcread``' intrinsic identifies reads of references from heap
+locations, allowing garbage collector implementations that require read
+barriers.
+
+Arguments:
+""""""""""
+
+The second argument is the address to read from, which should be an
+address allocated from the garbage collector. The first object is a
+pointer to the start of the referenced object, if needed by the language
+runtime (otherwise null).
+
+Semantics:
+""""""""""
+
+The '``llvm.gcread``' intrinsic has the same semantics as a load
+instruction, but may be replaced with substantially more complex code by
+the garbage collector runtime, as needed. The '``llvm.gcread``'
+intrinsic may only be used in a function which :ref:`specifies a GC
+algorithm <gc>`.
+
+.. _int_gcwrite:
+
+'``llvm.gcwrite``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
+
+Overview:
+"""""""""
+
+The '``llvm.gcwrite``' intrinsic identifies writes of references to heap
+locations, allowing garbage collector implementations that require write
+barriers (such as generational or reference counting collectors).
+
+Arguments:
+""""""""""
+
+The first argument is the reference to store, the second is the start of
+the object to store it to, and the third is the address of the field of
+Obj to store to. If the runtime does not require a pointer to the
+object, Obj may be null.
+
+Semantics:
+""""""""""
+
+The '``llvm.gcwrite``' intrinsic has the same semantics as a store
+instruction, but may be replaced with substantially more complex code by
+the garbage collector runtime, as needed. The '``llvm.gcwrite``'
+intrinsic may only be used in a function which :ref:`specifies a GC
+algorithm <gc>`.
+
+Code Generator Intrinsics
+-------------------------
+
+These intrinsics are provided by LLVM to expose special features that
+may only be implemented with code generator support.
+
+'``llvm.returnaddress``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8 *@llvm.returnaddress(i32 <level>)
+
+Overview:
+"""""""""
+
+The '``llvm.returnaddress``' intrinsic attempts to compute a
+target-specific value indicating the return address of the current
+function or one of its callers.
+
+Arguments:
+""""""""""
+
+The argument to this intrinsic indicates which function to return the
+address for. Zero indicates the calling function, one indicates its
+caller, etc. The argument is **required** to be a constant integer
+value.
+
+Semantics:
+""""""""""
+
+The '``llvm.returnaddress``' intrinsic either returns a pointer
+indicating the return address of the specified call frame, or zero if it
+cannot be identified. The value returned by this intrinsic is likely to
+be incorrect or 0 for arguments other than zero, so it should only be
+used for debugging purposes.
+
+Note that calling this intrinsic does not prevent function inlining or
+other aggressive transformations, so the value returned may not be that
+of the obvious source-language caller.
+
+'``llvm.frameaddress``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.frameaddress(i32 <level>)
+
+Overview:
+"""""""""
+
+The '``llvm.frameaddress``' intrinsic attempts to return the
+target-specific frame pointer value for the specified stack frame.
+
+Arguments:
+""""""""""
+
+The argument to this intrinsic indicates which function to return the
+frame pointer for. Zero indicates the calling function, one indicates
+its caller, etc. The argument is **required** to be a constant integer
+value.
+
+Semantics:
+""""""""""
+
+The '``llvm.frameaddress``' intrinsic either returns a pointer
+indicating the frame address of the specified call frame, or zero if it
+cannot be identified. The value returned by this intrinsic is likely to
+be incorrect or 0 for arguments other than zero, so it should only be
+used for debugging purposes.
+
+Note that calling this intrinsic does not prevent function inlining or
+other aggressive transformations, so the value returned may not be that
+of the obvious source-language caller.
+
+.. _int_stacksave:
+
+'``llvm.stacksave``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.stacksave()
+
+Overview:
+"""""""""
+
+The '``llvm.stacksave``' intrinsic is used to remember the current state
+of the function stack, for use with
+:ref:`llvm.stackrestore <int_stackrestore>`. This is useful for
+implementing language features like scoped automatic variable sized
+arrays in C99.
+
+Semantics:
+""""""""""
+
+This intrinsic returns a opaque pointer value that can be passed to
+:ref:`llvm.stackrestore <int_stackrestore>`. When an
+``llvm.stackrestore`` intrinsic is executed with a value saved from
+``llvm.stacksave``, it effectively restores the state of the stack to
+the state it was in when the ``llvm.stacksave`` intrinsic executed. In
+practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that
+were allocated after the ``llvm.stacksave`` was executed.
+
+.. _int_stackrestore:
+
+'``llvm.stackrestore``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.stackrestore(i8* %ptr)
+
+Overview:
+"""""""""
+
+The '``llvm.stackrestore``' intrinsic is used to restore the state of
+the function stack to the state it was in when the corresponding
+:ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is
+useful for implementing language features like scoped automatic variable
+sized arrays in C99.
+
+Semantics:
+""""""""""
+
+See the description for :ref:`llvm.stacksave <int_stacksave>`.
+
+'``llvm.prefetch``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
+
+Overview:
+"""""""""
+
+The '``llvm.prefetch``' intrinsic is a hint to the code generator to
+insert a prefetch instruction if supported; otherwise, it is a noop.
+Prefetches have no effect on the behavior of the program but can change
+its performance characteristics.
+
+Arguments:
+""""""""""
+
+``address`` is the address to be prefetched, ``rw`` is the specifier
+determining if the fetch should be for a read (0) or write (1), and
+``locality`` is a temporal locality specifier ranging from (0) - no
+locality, to (3) - extremely local keep in cache. The ``cache type``
+specifies whether the prefetch is performed on the data (1) or
+instruction (0) cache. The ``rw``, ``locality`` and ``cache type``
+arguments must be constant integers.
+
+Semantics:
+""""""""""
+
+This intrinsic does not modify the behavior of the program. In
+particular, prefetches cannot trap and do not produce a value. On
+targets that support this intrinsic, the prefetch can provide hints to
+the processor cache for better performance.
+
+'``llvm.pcmarker``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.pcmarker(i32 <id>)
+
+Overview:
+"""""""""
+
+The '``llvm.pcmarker``' intrinsic is a method to export a Program
+Counter (PC) in a region of code to simulators and other tools. The
+method is target specific, but it is expected that the marker will use
+exported symbols to transmit the PC of the marker. The marker makes no
+guarantees that it will remain with any specific instruction after
+optimizations. It is possible that the presence of a marker will inhibit
+optimizations. The intended use is to be inserted after optimizations to
+allow correlations of simulation runs.
+
+Arguments:
+""""""""""
+
+``id`` is a numerical id identifying the marker.
+
+Semantics:
+""""""""""
+
+This intrinsic does not modify the behavior of the program. Backends
+that do not support this intrinsic may ignore it.
+
+'``llvm.readcyclecounter``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i64 @llvm.readcyclecounter()
+
+Overview:
+"""""""""
+
+The '``llvm.readcyclecounter``' intrinsic provides access to the cycle
+counter register (or similar low latency, high accuracy clocks) on those
+targets that support it. On X86, it should map to RDTSC. On Alpha, it
+should map to RPCC. As the backing counters overflow quickly (on the
+order of 9 seconds on alpha), this should only be used for small
+timings.
+
+Semantics:
+""""""""""
+
+When directly supported, reading the cycle counter should not modify any
+memory. Implementations are allowed to either return a application
+specific value or a system wide value. On backends without support, this
+is lowered to a constant 0.
+
+Standard C Library Intrinsics
+-----------------------------
+
+LLVM provides intrinsics for a few important standard C library
+functions. These intrinsics allow source-language front-ends to pass
+information about the alignment of the pointer arguments to the code
+generator, providing opportunity for more efficient code generation.
+
+.. _int_memcpy:
+
+'``llvm.memcpy``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any
+integer bit width and for different address spaces. Not all targets
+support all bit widths however.
+
+::
+
+ declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
+
+Overview:
+"""""""""
+
+The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
+source location to the destination location.
+
+Note that, unlike the standard libc function, the ``llvm.memcpy.*``
+intrinsics do not return a value, takes extra alignment/isvolatile
+arguments and the pointers can be in specified address spaces.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to the destination, the second is a
+pointer to the source. The third argument is an integer argument
+specifying the number of bytes to copy, the fourth argument is the
+alignment of the source and destination locations, and the fifth is a
+boolean indicating a volatile access.
+
+If the call to this intrinsic has an alignment value that is not 0 or 1,
+then the caller guarantees that both the source and destination pointers
+are aligned to that boundary.
+
+If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is
+a :ref:`volatile operation <volatile>`. The detailed access behavior is not
+very cleanly specified and it is unwise to depend on it.
+
+Semantics:
+""""""""""
+
+The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
+source location to the destination location, which are not allowed to
+overlap. It copies "len" bytes of memory over. If the argument is known
+to be aligned to some boundary, this can be specified as the fourth
+argument, otherwise it should be set to 0 or 1.
+
+'``llvm.memmove``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use llvm.memmove on any integer
+bit width and for different address space. Not all targets support all
+bit widths however.
+
+::
+
+ declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
+
+Overview:
+"""""""""
+
+The '``llvm.memmove.*``' intrinsics move a block of memory from the
+source location to the destination location. It is similar to the
+'``llvm.memcpy``' intrinsic but allows the two memory locations to
+overlap.
+
+Note that, unlike the standard libc function, the ``llvm.memmove.*``
+intrinsics do not return a value, takes extra alignment/isvolatile
+arguments and the pointers can be in specified address spaces.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to the destination, the second is a
+pointer to the source. The third argument is an integer argument
+specifying the number of bytes to copy, the fourth argument is the
+alignment of the source and destination locations, and the fifth is a
+boolean indicating a volatile access.
+
+If the call to this intrinsic has an alignment value that is not 0 or 1,
+then the caller guarantees that the source and destination pointers are
+aligned to that boundary.
+
+If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call
+is a :ref:`volatile operation <volatile>`. The detailed access behavior is
+not very cleanly specified and it is unwise to depend on it.
+
+Semantics:
+""""""""""
+
+The '``llvm.memmove.*``' intrinsics copy a block of memory from the
+source location to the destination location, which may overlap. It
+copies "len" bytes of memory over. If the argument is known to be
+aligned to some boundary, this can be specified as the fourth argument,
+otherwise it should be set to 0 or 1.
+
+'``llvm.memset.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use llvm.memset on any integer
+bit width and for different address spaces. However, not all targets
+support all bit widths.
+
+::
+
+ declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>,
+ i32 <len>, i32 <align>, i1 <isvolatile>)
+ declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>,
+ i64 <len>, i32 <align>, i1 <isvolatile>)
+
+Overview:
+"""""""""
+
+The '``llvm.memset.*``' intrinsics fill a block of memory with a
+particular byte value.
+
+Note that, unlike the standard libc function, the ``llvm.memset``
+intrinsic does not return a value and takes extra alignment/volatile
+arguments. Also, the destination can be in an arbitrary address space.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to the destination to fill, the second
+is the byte value with which to fill it, the third argument is an
+integer argument specifying the number of bytes to fill, and the fourth
+argument is the known alignment of the destination location.
+
+If the call to this intrinsic has an alignment value that is not 0 or 1,
+then the caller guarantees that the destination pointer is aligned to
+that boundary.
+
+If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is
+a :ref:`volatile operation <volatile>`. The detailed access behavior is not
+very cleanly specified and it is unwise to depend on it.
+
+Semantics:
+""""""""""
+
+The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting
+at the destination location. If the argument is known to be aligned to
+some boundary, this can be specified as the fourth argument, otherwise
+it should be set to 0 or 1.
+
+'``llvm.sqrt.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.sqrt.f32(float %Val)
+ declare double @llvm.sqrt.f64(double %Val)
+ declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val)
+ declare fp128 @llvm.sqrt.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.sqrt``' intrinsics return the sqrt of the specified operand,
+returning the same value as the libm '``sqrt``' functions would. Unlike
+``sqrt`` in libm, however, ``llvm.sqrt`` has undefined behavior for
+negative numbers other than -0.0 (which allows for better optimization,
+because there is no need to worry about errno being set).
+``llvm.sqrt(-0.0)`` is defined to return -0.0 like IEEE sqrt.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the sqrt of the specified operand if it is a
+nonnegative floating point number.
+
+'``llvm.powi.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.powi`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.powi.f32(float %Val, i32 %power)
+ declare double @llvm.powi.f64(double %Val, i32 %power)
+ declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power)
+ declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power)
+ declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power)
+
+Overview:
+"""""""""
+
+The '``llvm.powi.*``' intrinsics return the first operand raised to the
+specified (positive or negative) power. The order of evaluation of
+multiplications is not defined. When a vector of floating point type is
+used, the second argument remains a scalar integer value.
+
+Arguments:
+""""""""""
+
+The second argument is an integer power, and the first is a value to
+raise to that power.
+
+Semantics:
+""""""""""
+
+This function returns the first value raised to the second power with an
+unspecified sequence of rounding operations.
+
+'``llvm.sin.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.sin`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.sin.f32(float %Val)
+ declare double @llvm.sin.f64(double %Val)
+ declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val)
+ declare fp128 @llvm.sin.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.sin.*``' intrinsics return the sine of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the sine of the specified operand, returning the
+same values as the libm ``sin`` functions would, and handles error
+conditions in the same way.
+
+'``llvm.cos.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.cos`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.cos.f32(float %Val)
+ declare double @llvm.cos.f64(double %Val)
+ declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val)
+ declare fp128 @llvm.cos.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.cos.*``' intrinsics return the cosine of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the cosine of the specified operand, returning the
+same values as the libm ``cos`` functions would, and handles error
+conditions in the same way.
+
+'``llvm.pow.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.pow`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.pow.f32(float %Val, float %Power)
+ declare double @llvm.pow.f64(double %Val, double %Power)
+ declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power)
+ declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power)
+ declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power)
+
+Overview:
+"""""""""
+
+The '``llvm.pow.*``' intrinsics return the first operand raised to the
+specified (positive or negative) power.
+
+Arguments:
+""""""""""
+
+The second argument is a floating point power, and the first is a value
+to raise to that power.
+
+Semantics:
+""""""""""
+
+This function returns the first value raised to the second power,
+returning the same values as the libm ``pow`` functions would, and
+handles error conditions in the same way.
+
+'``llvm.exp.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.exp`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.exp.f32(float %Val)
+ declare double @llvm.exp.f64(double %Val)
+ declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val)
+ declare fp128 @llvm.exp.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.exp.*``' intrinsics perform the exp function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``exp`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.exp2.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.exp2`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.exp2.f32(float %Val)
+ declare double @llvm.exp2.f64(double %Val)
+ declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val)
+ declare fp128 @llvm.exp2.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.exp2.*``' intrinsics perform the exp2 function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``exp2`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.log.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.log`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.log.f32(float %Val)
+ declare double @llvm.log.f64(double %Val)
+ declare x86_fp80 @llvm.log.f80(x86_fp80 %Val)
+ declare fp128 @llvm.log.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.log.*``' intrinsics perform the log function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``log`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.log10.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.log10`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.log10.f32(float %Val)
+ declare double @llvm.log10.f64(double %Val)
+ declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val)
+ declare fp128 @llvm.log10.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.log10.*``' intrinsics perform the log10 function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``log10`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.log2.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.log2`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.log2.f32(float %Val)
+ declare double @llvm.log2.f64(double %Val)
+ declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val)
+ declare fp128 @llvm.log2.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.log2.*``' intrinsics perform the log2 function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``log2`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.fma.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.fma`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.fma.f32(float %a, float %b, float %c)
+ declare double @llvm.fma.f64(double %a, double %b, double %c)
+ declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
+ declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
+ declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
+
+Overview:
+"""""""""
+
+The '``llvm.fma.*``' intrinsics perform the fused multiply-add
+operation.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``fma`` functions
+would.
+
+'``llvm.fabs.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.fabs`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.fabs.f32(float %Val)
+ declare double @llvm.fabs.f64(double %Val)
+ declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val)
+ declare fp128 @llvm.fabs.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.fabs.*``' intrinsics return the absolute value of the
+operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``fabs`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.floor.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.floor`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.floor.f32(float %Val)
+ declare double @llvm.floor.f64(double %Val)
+ declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val)
+ declare fp128 @llvm.floor.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.floor.*``' intrinsics return the floor of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``floor`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.ceil.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.ceil`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.ceil.f32(float %Val)
+ declare double @llvm.ceil.f64(double %Val)
+ declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val)
+ declare fp128 @llvm.ceil.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.ceil.*``' intrinsics return the ceiling of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``ceil`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.trunc.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.trunc`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.trunc.f32(float %Val)
+ declare double @llvm.trunc.f64(double %Val)
+ declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val)
+ declare fp128 @llvm.trunc.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.trunc.*``' intrinsics returns the operand rounded to the
+nearest integer not larger in magnitude than the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``trunc`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.rint.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.rint`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.rint.f32(float %Val)
+ declare double @llvm.rint.f64(double %Val)
+ declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val)
+ declare fp128 @llvm.rint.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.rint.*``' intrinsics returns the operand rounded to the
+nearest integer. It may raise an inexact floating-point exception if the
+operand isn't an integer.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``rint`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.nearbyint.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.nearbyint.f32(float %Val)
+ declare double @llvm.nearbyint.f64(double %Val)
+ declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val)
+ declare fp128 @llvm.nearbyint.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the
+nearest integer.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``nearbyint``
+functions would, and handles error conditions in the same way.
+
+Bit Manipulation Intrinsics
+---------------------------
+
+LLVM provides intrinsics for a few important bit manipulation
+operations. These allow efficient code generation for some algorithms.
+
+'``llvm.bswap.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic function. You can use bswap on any
+integer type that is an even number of bytes (i.e. BitWidth % 16 == 0).
+
+::
+
+ declare i16 @llvm.bswap.i16(i16 <id>)
+ declare i32 @llvm.bswap.i32(i32 <id>)
+ declare i64 @llvm.bswap.i64(i64 <id>)
+
+Overview:
+"""""""""
+
+The '``llvm.bswap``' family of intrinsics is used to byte swap integer
+values with an even number of bytes (positive multiple of 16 bits).
+These are useful for performing operations on data that is not in the
+target's native byte order.
+
+Semantics:
+""""""""""
+
+The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high
+and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32``
+intrinsic returns an i32 value that has the four bytes of the input i32
+swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the
+returned i32 will have its bytes in 3, 2, 1, 0 order. The
+``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this
+concept to additional even-byte lengths (6 bytes, 8 bytes and more,
+respectively).
+
+'``llvm.ctpop.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use llvm.ctpop on any integer
+bit width, or on any vector with integer elements. Not all targets
+support all bit widths or vector types, however.
+
+::
+
+ declare i8 @llvm.ctpop.i8(i8 <src>)
+ declare i16 @llvm.ctpop.i16(i16 <src>)
+ declare i32 @llvm.ctpop.i32(i32 <src>)
+ declare i64 @llvm.ctpop.i64(i64 <src>)
+ declare i256 @llvm.ctpop.i256(i256 <src>)
+ declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)
+
+Overview:
+"""""""""
+
+The '``llvm.ctpop``' family of intrinsics counts the number of bits set
+in a value.
+
+Arguments:
+""""""""""
+
+The only argument is the value to be counted. The argument may be of any
+integer type, or a vector with integer elements. The return type must
+match the argument type.
+
+Semantics:
+""""""""""
+
+The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within
+each element of a vector.
+
+'``llvm.ctlz.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any
+integer bit width, or any vector whose elements are integers. Not all
+targets support all bit widths or vector types, however.
+
+::
+
+ declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>)
+ declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>)
+ declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>)
+ declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>)
+ declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
+ declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
+
+Overview:
+"""""""""
+
+The '``llvm.ctlz``' family of intrinsic functions counts the number of
+leading zeros in a variable.
+
+Arguments:
+""""""""""
+
+The first argument is the value to be counted. This argument may be of
+any integer type, or a vectory with integer element type. The return
+type must match the first argument type.
+
+The second argument must be a constant and is a flag to indicate whether
+the intrinsic should ensure that a zero as the first argument produces a
+defined result. Historically some architectures did not provide a
+defined result for zero values as efficiently, and many algorithms are
+now predicated on avoiding zero-value inputs.
+
+Semantics:
+""""""""""
+
+The '``llvm.ctlz``' intrinsic counts the leading (most significant)
+zeros in a variable, or within each element of the vector. If
+``src == 0`` then the result is the size in bits of the type of ``src``
+if ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
+``llvm.ctlz(i32 2) = 30``.
+
+'``llvm.cttz.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.cttz`` on any
+integer bit width, or any vector of integer elements. Not all targets
+support all bit widths or vector types, however.
+
+::
+
+ declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>)
+ declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>)
+ declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>)
+ declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>)
+ declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
+ declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
+
+Overview:
+"""""""""
+
+The '``llvm.cttz``' family of intrinsic functions counts the number of
+trailing zeros.
+
+Arguments:
+""""""""""
+
+The first argument is the value to be counted. This argument may be of
+any integer type, or a vectory with integer element type. The return
+type must match the first argument type.
+
+The second argument must be a constant and is a flag to indicate whether
+the intrinsic should ensure that a zero as the first argument produces a
+defined result. Historically some architectures did not provide a
+defined result for zero values as efficiently, and many algorithms are
+now predicated on avoiding zero-value inputs.
+
+Semantics:
+""""""""""
+
+The '``llvm.cttz``' intrinsic counts the trailing (least significant)
+zeros in a variable, or within each element of a vector. If ``src == 0``
+then the result is the size in bits of the type of ``src`` if
+``is_zero_undef == 0`` and ``undef`` otherwise. For example,
+``llvm.cttz(2) = 1``.
+
+Arithmetic with Overflow Intrinsics
+-----------------------------------
+
+LLVM provides intrinsics for some arithmetic with overflow operations.
+
+'``llvm.sadd.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``
+on any integer bit width.
+
+::
+
+ declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
+
+Overview:
+"""""""""
+
+The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
+a signed addition of the two arguments, and indicate whether an overflow
+occurred during the signed summation.
+
+Arguments:
+""""""""""
+
+The arguments (%a and %b) and the first element of the result structure
+may be of integer types of any bit width, but they must have the same
+bit width. The second element of the result structure must be of type
+``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
+addition.
+
+Semantics:
+""""""""""
+
+The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
+a signed addition of the two variables. They return a structure — the
+first element of which is the signed summation, and the second element
+of which is a bit specifying if the signed summation resulted in an
+overflow.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+
+'``llvm.uadd.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow``
+on any integer bit width.
+
+::
+
+ declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
+
+Overview:
+"""""""""
+
+The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
+an unsigned addition of the two arguments, and indicate whether a carry
+occurred during the unsigned summation.
+
+Arguments:
+""""""""""
+
+The arguments (%a and %b) and the first element of the result structure
+may be of integer types of any bit width, but they must have the same
+bit width. The second element of the result structure must be of type
+``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
+addition.
+
+Semantics:
+""""""""""
+
+The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
+an unsigned addition of the two arguments. They return a structure — the
+first element of which is the sum, and the second element of which is a
+bit specifying if the unsigned summation resulted in a carry.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %carry, label %normal
+
+'``llvm.ssub.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow``
+on any integer bit width.
+
+::
+
+ declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
+
+Overview:
+"""""""""
+
+The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
+a signed subtraction of the two arguments, and indicate whether an
+overflow occurred during the signed subtraction.
+
+Arguments:
+""""""""""
+
+The arguments (%a and %b) and the first element of the result structure
+may be of integer types of any bit width, but they must have the same
+bit width. The second element of the result structure must be of type
+``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
+subtraction.
+
+Semantics:
+""""""""""
+
+The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
+a signed subtraction of the two arguments. They return a structure — the
+first element of which is the subtraction, and the second element of
+which is a bit specifying if the signed subtraction resulted in an
+overflow.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+
+'``llvm.usub.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow``
+on any integer bit width.
+
+::
+
+ declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
+
+Overview:
+"""""""""
+
+The '``llvm.usub.with.overflow``' family of intrinsic functions perform
+an unsigned subtraction of the two arguments, and indicate whether an
+overflow occurred during the unsigned subtraction.
+
+Arguments:
+""""""""""
+
+The arguments (%a and %b) and the first element of the result structure
+may be of integer types of any bit width, but they must have the same
+bit width. The second element of the result structure must be of type
+``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
+subtraction.
+
+Semantics:
+""""""""""
+
+The '``llvm.usub.with.overflow``' family of intrinsic functions perform
+an unsigned subtraction of the two arguments. They return a structure —
+the first element of which is the subtraction, and the second element of
+which is a bit specifying if the unsigned subtraction resulted in an
+overflow.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+
+'``llvm.smul.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow``
+on any integer bit width.
+
+::
+
+ declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
+
+Overview:
+"""""""""
+
+The '``llvm.smul.with.overflow``' family of intrinsic functions perform
+a signed multiplication of the two arguments, and indicate whether an
+overflow occurred during the signed multiplication.
+
+Arguments:
+""""""""""
+
+The arguments (%a and %b) and the first element of the result structure
+may be of integer types of any bit width, but they must have the same
+bit width. The second element of the result structure must be of type
+``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
+multiplication.
+
+Semantics:
+""""""""""
+
+The '``llvm.smul.with.overflow``' family of intrinsic functions perform
+a signed multiplication of the two arguments. They return a structure —
+the first element of which is the multiplication, and the second element
+of which is a bit specifying if the signed multiplication resulted in an
+overflow.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+
+'``llvm.umul.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow``
+on any integer bit width.
+
+::
+
+ declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
+ declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
+ declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
+
+Overview:
+"""""""""
+
+The '``llvm.umul.with.overflow``' family of intrinsic functions perform
+a unsigned multiplication of the two arguments, and indicate whether an
+overflow occurred during the unsigned multiplication.
+
+Arguments:
+""""""""""
+
+The arguments (%a and %b) and the first element of the result structure
+may be of integer types of any bit width, but they must have the same
+bit width. The second element of the result structure must be of type
+``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
+multiplication.
+
+Semantics:
+""""""""""
+
+The '``llvm.umul.with.overflow``' family of intrinsic functions perform
+an unsigned multiplication of the two arguments. They return a structure
+— the first element of which is the multiplication, and the second
+element of which is a bit specifying if the unsigned multiplication
+resulted in an overflow.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
+ %sum = extractvalue {i32, i1} %res, 0
+ %obit = extractvalue {i32, i1} %res, 1
+ br i1 %obit, label %overflow, label %normal
+
+Specialised Arithmetic Intrinsics
+---------------------------------
+
+'``llvm.fmuladd.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
+ declare double @llvm.fmuladd.f64(double %a, double %b, double %c)
+
+Overview:
+"""""""""
+
+The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add
+expressions that can be fused if the code generator determines that the
+fused expression would be legal and efficient.
+
+Arguments:
+""""""""""
+
+The '``llvm.fmuladd.*``' intrinsics each take three arguments: two
+multiplicands, a and b, and an addend c.
+
+Semantics:
+""""""""""
+
+The expression:
+
+::
+
+ %0 = call float @llvm.fmuladd.f32(%a, %b, %c)
+
+is equivalent to the expression a \* b + c, except that rounding will
+not be performed between the multiplication and addition steps if the
+code generator fuses the operations. Fusion is not guaranteed, even if
+the target platform supports it. If a fused multiply-add is required the
+corresponding llvm.fma.\* intrinsic function should be used instead.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields {float}:r2 = (a * b) + c
+
+Half Precision Floating Point Intrinsics
+----------------------------------------
+
+For most target platforms, half precision floating point is a
+storage-only format. This means that it is a dense encoding (in memory)
+but does not support computation in the format.
+
+This means that code must first load the half-precision floating point
+value as an i16, then convert it to float with
+:ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can
+then be performed on the float value (including extending to double
+etc). To store the value back to memory, it is first converted to float
+if needed, then converted to i16 with
+:ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an
+i16 value.
+
+.. _int_convert_to_fp16:
+
+'``llvm.convert.to.fp16``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i16 @llvm.convert.to.fp16(f32 %a)
+
+Overview:
+"""""""""
+
+The '``llvm.convert.to.fp16``' intrinsic function performs a conversion
+from single precision floating point format to half precision floating
+point format.
+
+Arguments:
+""""""""""
+
+The intrinsic function contains single argument - the value to be
+converted.
+
+Semantics:
+""""""""""
+
+The '``llvm.convert.to.fp16``' intrinsic function performs a conversion
+from single precision floating point format to half precision floating
+point format. The return value is an ``i16`` which contains the
+converted number.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call i16 @llvm.convert.to.fp16(f32 %a)
+ store i16 %res, i16* @x, align 2
+
+.. _int_convert_from_fp16:
+
+'``llvm.convert.from.fp16``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare f32 @llvm.convert.from.fp16(i16 %a)
+
+Overview:
+"""""""""
+
+The '``llvm.convert.from.fp16``' intrinsic function performs a
+conversion from half precision floating point format to single precision
+floating point format.
+
+Arguments:
+""""""""""
+
+The intrinsic function contains single argument - the value to be
+converted.
+
+Semantics:
+""""""""""
+
+The '``llvm.convert.from.fp16``' intrinsic function performs a
+conversion from half single precision floating point format to single
+precision floating point format. The input half-float value is
+represented by an ``i16`` value.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %a = load i16* @x, align 2
+ %res = call f32 @llvm.convert.from.fp16(i16 %a)
+
+Debugger Intrinsics
+-------------------
+
+The LLVM debugger intrinsics (which all start with ``llvm.dbg.``
+prefix), are described in the `LLVM Source Level
+Debugging <SourceLevelDebugging.html#format_common_intrinsics>`_
+document.
+
+Exception Handling Intrinsics
+-----------------------------
+
+The LLVM exception handling intrinsics (which all start with
+``llvm.eh.`` prefix), are described in the `LLVM Exception
+Handling <ExceptionHandling.html#format_common_intrinsics>`_ document.
+
+.. _int_trampoline:
+
+Trampoline Intrinsics
+---------------------
+
+These intrinsics make it possible to excise one parameter, marked with
+the :ref:`nest <nest>` attribute, from a function. The result is a
+callable function pointer lacking the nest parameter - the caller does
+not need to provide a value for it. Instead, the value to use is stored
+in advance in a "trampoline", a block of memory usually allocated on the
+stack, which also contains code to splice the nest value into the
+argument list. This is used to implement the GCC nested function address
+extension.
+
+For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)``
+then the resulting function pointer has signature ``i32 (i32, i32)*``.
+It can be created as follows:
+
+.. code-block:: llvm
+
+ %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
+ %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
+ call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
+ %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
+ %fp = bitcast i8* %p to i32 (i32, i32)*
+
+The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to
+``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``.
+
+.. _int_it:
+
+'``llvm.init.trampoline``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
+
+Overview:
+"""""""""
+
+This fills the memory pointed to by ``tramp`` with executable code,
+turning it into a trampoline.
+
+Arguments:
+""""""""""
+
+The ``llvm.init.trampoline`` intrinsic takes three arguments, all
+pointers. The ``tramp`` argument must point to a sufficiently large and
+sufficiently aligned block of memory; this memory is written to by the
+intrinsic. Note that the size and the alignment are target-specific -
+LLVM currently provides no portable way of determining them, so a
+front-end that generates this intrinsic needs to have some
+target-specific knowledge. The ``func`` argument must hold a function
+bitcast to an ``i8*``.
+
+Semantics:
+""""""""""
+
+The block of memory pointed to by ``tramp`` is filled with target
+dependent code, turning it into a function. Then ``tramp`` needs to be
+passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can
+be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new
+function's signature is the same as that of ``func`` with any arguments
+marked with the ``nest`` attribute removed. At most one such ``nest``
+argument is allowed, and it must be of pointer type. Calling the new
+function is equivalent to calling ``func`` with the same argument list,
+but with ``nval`` used for the missing ``nest`` argument. If, after
+calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is
+modified, then the effect of any later call to the returned function
+pointer is undefined.
+
+.. _int_at:
+
+'``llvm.adjust.trampoline``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.adjust.trampoline(i8* <tramp>)
+
+Overview:
+"""""""""
+
+This performs any required machine-specific adjustment to the address of
+a trampoline (passed as ``tramp``).
+
+Arguments:
+""""""""""
+
+``tramp`` must point to a block of memory which already has trampoline
+code filled in by a previous call to
+:ref:`llvm.init.trampoline <int_it>`.
+
+Semantics:
+""""""""""
+
+On some architectures the address of the code to be executed needs to be
+different to the address where the trampoline is actually stored. This
+intrinsic returns the executable address corresponding to ``tramp``
+after performing the required machine specific adjustments. The pointer
+returned can then be :ref:`bitcast and executed <int_trampoline>`.
+
+Memory Use Markers
+------------------
+
+This class of intrinsics exists to information about the lifetime of
+memory objects and ranges where variables are immutable.
+
+'``llvm.lifetime.start``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.lifetime.start``' intrinsic specifies the start of a memory
+object's lifetime.
+
+Arguments:
+""""""""""
+
+The first argument is a constant integer representing the size of the
+object, or -1 if it is variable sized. The second argument is a pointer
+to the object.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that before this point in the code, the value
+of the memory pointed to by ``ptr`` is dead. This means that it is known
+to never be used and has an undefined value. A load from the pointer
+that precedes this intrinsic can be replaced with ``'undef'``.
+
+'``llvm.lifetime.end``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.lifetime.end``' intrinsic specifies the end of a memory
+object's lifetime.
+
+Arguments:
+""""""""""
+
+The first argument is a constant integer representing the size of the
+object, or -1 if it is variable sized. The second argument is a pointer
+to the object.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that after this point in the code, the value of
+the memory pointed to by ``ptr`` is dead. This means that it is known to
+never be used and has an undefined value. Any stores into the memory
+object following this intrinsic may be removed as dead.
+
+'``llvm.invariant.start``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.invariant.start``' intrinsic specifies that the contents of
+a memory object will not change.
+
+Arguments:
+""""""""""
+
+The first argument is a constant integer representing the size of the
+object, or -1 if it is variable sized. The second argument is a pointer
+to the object.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that until an ``llvm.invariant.end`` that uses
+the return value, the referenced memory location is constant and
+unchanging.
+
+'``llvm.invariant.end``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.invariant.end``' intrinsic specifies that the contents of a
+memory object are mutable.
+
+Arguments:
+""""""""""
+
+The first argument is the matching ``llvm.invariant.start`` intrinsic.
+The second argument is a constant integer representing the size of the
+object, or -1 if it is variable sized and the third argument is a
+pointer to the object.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that the memory is mutable again.
+
+General Intrinsics
+------------------
+
+This class of intrinsics is designed to be generic and has no specific
+purpose.
+
+'``llvm.var.annotation``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
+
+Overview:
+"""""""""
+
+The '``llvm.var.annotation``' intrinsic.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to a value, the second is a pointer to a
+global string, the third is a pointer to a global string which is the
+source file name, and the last argument is the line number.
+
+Semantics:
+""""""""""
+
+This intrinsic allows annotation of local variables with arbitrary
+strings. This can be useful for special purpose optimizations that want
+to look for these annotations. These have no other defined use; they are
+ignored by code generation and optimization.
+
+'``llvm.annotation.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use '``llvm.annotation``' on
+any integer bit width.
+
+::
+
+ declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>)
+
+Overview:
+"""""""""
+
+The '``llvm.annotation``' intrinsic.
+
+Arguments:
+""""""""""
+
+The first argument is an integer value (result of some expression), the
+second is a pointer to a global string, the third is a pointer to a
+global string which is the source file name, and the last argument is
+the line number. It returns the value of the first argument.
+
+Semantics:
+""""""""""
+
+This intrinsic allows annotations to be put on arbitrary expressions
+with arbitrary strings. This can be useful for special purpose
+optimizations that want to look for these annotations. These have no
+other defined use; they are ignored by code generation and optimization.
+
+'``llvm.trap``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.trap() noreturn nounwind
+
+Overview:
+"""""""""
+
+The '``llvm.trap``' intrinsic.
+
+Arguments:
+""""""""""
+
+None.
+
+Semantics:
+""""""""""
+
+This intrinsic is lowered to the target dependent trap instruction. If
+the target does not have a trap instruction, this intrinsic will be
+lowered to a call of the ``abort()`` function.
+
+'``llvm.debugtrap``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.debugtrap() nounwind
+
+Overview:
+"""""""""
+
+The '``llvm.debugtrap``' intrinsic.
+
+Arguments:
+""""""""""
+
+None.
+
+Semantics:
+""""""""""
+
+This intrinsic is lowered to code which is intended to cause an
+execution trap with the intention of requesting the attention of a
+debugger.
+
+'``llvm.stackprotector``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
+
+Overview:
+"""""""""
+
+The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it
+onto the stack at ``slot``. The stack slot is adjusted to ensure that it
+is placed on the stack before local variables.
+
+Arguments:
+""""""""""
+
+The ``llvm.stackprotector`` intrinsic requires two pointer arguments.
+The first argument is the value loaded from the stack guard
+``@__stack_chk_guard``. The second variable is an ``alloca`` that has
+enough space to hold the value of the guard.
+
+Semantics:
+""""""""""
+
+This intrinsic causes the prologue/epilogue inserter to force the
+position of the ``AllocaInst`` stack slot to be before local variables
+on the stack. This is to ensure that if a local variable on the stack is
+overwritten, it will destroy the value of the guard. When the function
+exits, the guard on the stack is checked against the original guard. If
+they are different, then the program aborts by calling the
+``__stack_chk_fail()`` function.
+
+'``llvm.objectsize``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>)
+ declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>)
+
+Overview:
+"""""""""
+
+The ``llvm.objectsize`` intrinsic is designed to provide information to
+the optimizers to determine at compile time whether a) an operation
+(like memcpy) will overflow a buffer that corresponds to an object, or
+b) that a runtime check for overflow isn't necessary. An object in this
+context means an allocation of a specific class, structure, array, or
+other object.
+
+Arguments:
+""""""""""
+
+The ``llvm.objectsize`` intrinsic takes two arguments. The first
+argument is a pointer to or into the ``object``. The second argument is
+a boolean and determines whether ``llvm.objectsize`` returns 0 (if true)
+or -1 (if false) when the object size is unknown. The second argument
+only accepts constants.
+
+Semantics:
+""""""""""
+
+The ``llvm.objectsize`` intrinsic is lowered to a constant representing
+the size of the object concerned. If the size cannot be determined at
+compile time, ``llvm.objectsize`` returns ``i32/i64 -1 or 0`` (depending
+on the ``min`` argument).
+
+'``llvm.expect``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
+ declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)
+
+Overview:
+"""""""""
+
+The ``llvm.expect`` intrinsic provides information about expected (the
+most probable) value of ``val``, which can be used by optimizers.
+
+Arguments:
+""""""""""
+
+The ``llvm.expect`` intrinsic takes two arguments. The first argument is
+a value. The second argument is an expected value, this needs to be a
+constant value, variables are not allowed.
+
+Semantics:
+""""""""""
+
+This intrinsic is lowered to the ``val``.
+
+'``llvm.donothing``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.donothing() nounwind readnone
+
+Overview:
+"""""""""
+
+The ``llvm.donothing`` intrinsic doesn't perform any operation. It's the
+only intrinsic that can be called with an invoke instruction.
+
+Arguments:
+""""""""""
+
+None.
+
+Semantics:
+""""""""""
+
+This intrinsic does nothing, and it's removed by optimizers and ignored
+by codegen.
projects / platform / upstream / llvm.git / commitdiff