1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2 "http://www.w3.org/TR/html4/strict.dtd"> 3 <html> 4 <head> 5 <title>LLVM Assembly Language Reference Manual</title> 6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 7 <meta name="author" content="Chris Lattner"> 8 <meta name="description" 9 content="LLVM Assembly Language Reference Manual."> 10 <link rel="stylesheet" href="llvm.css" type="text/css"> 11 </head> 12 13 <body> 14 15 <h1>LLVM Language Reference Manual</h1> 16 <ol> 17 <li><a href="#abstract">Abstract</a></li> 18 <li><a href="#introduction">Introduction</a></li> 19 <li><a href="#identifiers">Identifiers</a></li> 20 <li><a href="#highlevel">High Level Structure</a> 21 <ol> 22 <li><a href="#modulestructure">Module Structure</a></li> 23 <li><a href="#linkage">Linkage Types</a> 24 <ol> 25 <li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li> 26 <li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li> 27 <li><a href="#linkage_linker_private_weak">'<tt>linker_private_weak</tt>' Linkage</a></li> 28 <li><a href="#linkage_linker_private_weak_def_auto">'<tt>linker_private_weak_def_auto</tt>' Linkage</a></li> 29 <li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li> 30 <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li> 31 <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li> 32 <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li> 33 <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li> 34 <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li> 35 <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li> 36 <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li> 37 <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li> 38 <li><a href="#linkage_external">'<tt>external</tt>' Linkage</a></li> 39 <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li> 40 <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li> 41 </ol> 42 </li> 43 <li><a href="#callingconv">Calling Conventions</a></li> 44 <li><a href="#namedtypes">Named Types</a></li> 45 <li><a href="#globalvars">Global Variables</a></li> 46 <li><a href="#functionstructure">Functions</a></li> 47 <li><a href="#aliasstructure">Aliases</a></li> 48 <li><a href="#namedmetadatastructure">Named Metadata</a></li> 49 <li><a href="#paramattrs">Parameter Attributes</a></li> 50 <li><a href="#fnattrs">Function Attributes</a></li> 51 <li><a href="#gc">Garbage Collector Names</a></li> 52 <li><a href="#moduleasm">Module-Level Inline Assembly</a></li> 53 <li><a href="#datalayout">Data Layout</a></li> 54 <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li> 55 <li><a href="#volatile">Volatile Memory Accesses</a></li> 56 <li><a href="#memmodel">Memory Model for Concurrent Operations</a></li> 57 <li><a href="#ordering">Atomic Memory Ordering Constraints</a></li> 58 </ol> 59 </li> 60 <li><a href="#typesystem">Type System</a> 61 <ol> 62 <li><a href="#t_classifications">Type Classifications</a></li> 63 <li><a href="#t_primitive">Primitive Types</a> 64 <ol> 65 <li><a href="#t_integer">Integer Type</a></li> 66 <li><a href="#t_floating">Floating Point Types</a></li> 67 <li><a href="#t_x86mmx">X86mmx Type</a></li> 68 <li><a href="#t_void">Void Type</a></li> 69 <li><a href="#t_label">Label Type</a></li> 70 <li><a href="#t_metadata">Metadata Type</a></li> 71 </ol> 72 </li> 73 <li><a href="#t_derived">Derived Types</a> 74 <ol> 75 <li><a href="#t_aggregate">Aggregate Types</a> 76 <ol> 77 <li><a href="#t_array">Array Type</a></li> 78 <li><a href="#t_struct">Structure Type</a></li> 79 <li><a href="#t_opaque">Opaque Structure Types</a></li> 80 <li><a href="#t_vector">Vector Type</a></li> 81 </ol> 82 </li> 83 <li><a href="#t_function">Function Type</a></li> 84 <li><a href="#t_pointer">Pointer Type</a></li> 85 </ol> 86 </li> 87 </ol> 88 </li> 89 <li><a href="#constants">Constants</a> 90 <ol> 91 <li><a href="#simpleconstants">Simple Constants</a></li> 92 <li><a href="#complexconstants">Complex Constants</a></li> 93 <li><a href="#globalconstants">Global Variable and Function Addresses</a></li> 94 <li><a href="#undefvalues">Undefined Values</a></li> 95 <li><a href="#trapvalues">Trap Values</a></li> 96 <li><a href="#blockaddress">Addresses of Basic Blocks</a></li> 97 <li><a href="#constantexprs">Constant Expressions</a></li> 98 </ol> 99 </li> 100 <li><a href="#othervalues">Other Values</a> 101 <ol> 102 <li><a href="#inlineasm">Inline Assembler Expressions</a></li> 103 <li><a href="#metadata">Metadata Nodes and Metadata Strings</a></li> 104 </ol> 105 </li> 106 <li><a href="#intrinsic_globals">Intrinsic Global Variables</a> 107 <ol> 108 <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li> 109 <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>' 110 Global Variable</a></li> 111 <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>' 112 Global Variable</a></li> 113 <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>' 114 Global Variable</a></li> 115 </ol> 116 </li> 117 <li><a href="#instref">Instruction Reference</a> 118 <ol> 119 <li><a href="#terminators">Terminator Instructions</a> 120 <ol> 121 <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li> 122 <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li> 123 <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li> 124 <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li> 125 <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li> 126 <li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li> 127 <li><a href="#i_resume">'<tt>resume</tt>' Instruction</a></li> 128 <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li> 129 </ol> 130 </li> 131 <li><a href="#binaryops">Binary Operations</a> 132 <ol> 133 <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li> 134 <li><a href="#i_fadd">'<tt>fadd</tt>' Instruction</a></li> 135 <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li> 136 <li><a href="#i_fsub">'<tt>fsub</tt>' Instruction</a></li> 137 <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li> 138 <li><a href="#i_fmul">'<tt>fmul</tt>' Instruction</a></li> 139 <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li> 140 <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li> 141 <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li> 142 <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li> 143 <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li> 144 <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li> 145 </ol> 146 </li> 147 <li><a href="#bitwiseops">Bitwise Binary Operations</a> 148 <ol> 149 <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li> 150 <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li> 151 <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li> 152 <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li> 153 <li><a href="#i_or">'<tt>or</tt>' Instruction</a></li> 154 <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li> 155 </ol> 156 </li> 157 <li><a href="#vectorops">Vector Operations</a> 158 <ol> 159 <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li> 160 <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li> 161 <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li> 162 </ol> 163 </li> 164 <li><a href="#aggregateops">Aggregate Operations</a> 165 <ol> 166 <li><a href="#i_extractvalue">'<tt>extractvalue</tt>' Instruction</a></li> 167 <li><a href="#i_insertvalue">'<tt>insertvalue</tt>' Instruction</a></li> 168 </ol> 169 </li> 170 <li><a href="#memoryops">Memory Access and Addressing Operations</a> 171 <ol> 172 <li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li> 173 <li><a href="#i_load">'<tt>load</tt>' Instruction</a></li> 174 <li><a href="#i_store">'<tt>store</tt>' Instruction</a></li> 175 <li><a href="#i_fence">'<tt>fence</tt>' Instruction</a></li> 176 <li><a href="#i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a></li> 177 <li><a href="#i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a></li> 178 <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li> 179 </ol> 180 </li> 181 <li><a href="#convertops">Conversion Operations</a> 182 <ol> 183 <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li> 184 <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li> 185 <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li> 186 <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li> 187 <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li> 188 <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li> 189 <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li> 190 <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li> 191 <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li> 192 <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li> 193 <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li> 194 <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li> 195 </ol> 196 </li> 197 <li><a href="#otherops">Other Operations</a> 198 <ol> 199 <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li> 200 <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li> 201 <li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li> 202 <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li> 203 <li><a href="#i_call">'<tt>call</tt>' Instruction</a></li> 204 <li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a></li> 205 <li><a href="#i_landingpad">'<tt>landingpad</tt>' Instruction</a></li> 206 </ol> 207 </li> 208 </ol> 209 </li> 210 <li><a href="#intrinsics">Intrinsic Functions</a> 211 <ol> 212 <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a> 213 <ol> 214 <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li> 215 <li><a href="#int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li> 216 <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a></li> 217 </ol> 218 </li> 219 <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a> 220 <ol> 221 <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li> 222 <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li> 223 <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li> 224 </ol> 225 </li> 226 <li><a href="#int_codegen">Code Generator Intrinsics</a> 227 <ol> 228 <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li> 229 <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li> 230 <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li> 231 <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li> 232 <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li> 233 <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li> 234 <li><a href="#int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a></li> 235 </ol> 236 </li> 237 <li><a href="#int_libc">Standard C Library Intrinsics</a> 238 <ol> 239 <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li> 240 <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li> 241 <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li> 242 <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li> 243 <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li> 244 <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li> 245 <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li> 246 <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li> 247 <li><a href="#int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a></li> 248 <li><a href="#int_log">'<tt>llvm.log.*</tt>' Intrinsic</a></li> 249 <li><a href="#int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a></li> 250 </ol> 251 </li> 252 <li><a href="#int_manip">Bit Manipulation Intrinsics</a> 253 <ol> 254 <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li> 255 <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li> 256 <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li> 257 <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li> 258 </ol> 259 </li> 260 <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a> 261 <ol> 262 <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li> 263 <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li> 264 <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li> 265 <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li> 266 <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li> 267 <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li> 268 </ol> 269 </li> 270 <li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a> 271 <ol> 272 <li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li> 273 <li><a href="#int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a></li> 274 </ol> 275 </li> 276 <li><a href="#int_debugger">Debugger intrinsics</a></li> 277 <li><a href="#int_eh">Exception Handling intrinsics</a></li> 278 <li><a href="#int_trampoline">Trampoline Intrinsics</a> 279 <ol> 280 <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li> 281 <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</a></li> 282 </ol> 283 </li> 284 <li><a href="#int_atomics">Atomic intrinsics</a> 285 <ol> 286 <li><a href="#int_memory_barrier"><tt>llvm.memory_barrier</tt></a></li> 287 <li><a href="#int_atomic_cmp_swap"><tt>llvm.atomic.cmp.swap</tt></a></li> 288 <li><a href="#int_atomic_swap"><tt>llvm.atomic.swap</tt></a></li> 289 <li><a href="#int_atomic_load_add"><tt>llvm.atomic.load.add</tt></a></li> 290 <li><a href="#int_atomic_load_sub"><tt>llvm.atomic.load.sub</tt></a></li> 291 <li><a href="#int_atomic_load_and"><tt>llvm.atomic.load.and</tt></a></li> 292 <li><a href="#int_atomic_load_nand"><tt>llvm.atomic.load.nand</tt></a></li> 293 <li><a href="#int_atomic_load_or"><tt>llvm.atomic.load.or</tt></a></li> 294 <li><a href="#int_atomic_load_xor"><tt>llvm.atomic.load.xor</tt></a></li> 295 <li><a href="#int_atomic_load_max"><tt>llvm.atomic.load.max</tt></a></li> 296 <li><a href="#int_atomic_load_min"><tt>llvm.atomic.load.min</tt></a></li> 297 <li><a href="#int_atomic_load_umax"><tt>llvm.atomic.load.umax</tt></a></li> 298 <li><a href="#int_atomic_load_umin"><tt>llvm.atomic.load.umin</tt></a></li> 299 </ol> 300 </li> 301 <li><a href="#int_memorymarkers">Memory Use Markers</a> 302 <ol> 303 <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li> 304 <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li> 305 <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li> 306 <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li> 307 </ol> 308 </li> 309 <li><a href="#int_general">General intrinsics</a> 310 <ol> 311 <li><a href="#int_var_annotation"> 312 '<tt>llvm.var.annotation</tt>' Intrinsic</a></li> 313 <li><a href="#int_annotation"> 314 '<tt>llvm.annotation.*</tt>' Intrinsic</a></li> 315 <li><a href="#int_trap"> 316 '<tt>llvm.trap</tt>' Intrinsic</a></li> 317 <li><a href="#int_stackprotector"> 318 '<tt>llvm.stackprotector</tt>' Intrinsic</a></li> 319 <li><a href="#int_objectsize"> 320 '<tt>llvm.objectsize</tt>' Intrinsic</a></li> 321 </ol> 322 </li> 323 </ol> 324 </li> 325 </ol> 326 327 <div class="doc_author"> 328 <p>Written by <a href="mailto:sabre (a] nondot.org">Chris Lattner</a> 329 and <a href="mailto:vadve (a] cs.uiuc.edu">Vikram Adve</a></p> 330 </div> 331 332 <!-- *********************************************************************** --> 333 <h2><a name="abstract">Abstract</a></h2> 334 <!-- *********************************************************************** --> 335 336 <div> 337 338 <p>This document is a reference manual for the LLVM assembly language. LLVM is 339 a Static Single Assignment (SSA) based representation that provides type 340 safety, low-level operations, flexibility, and the capability of representing 341 'all' high-level languages cleanly. It is the common code representation 342 used throughout all phases of the LLVM compilation strategy.</p> 343 344 </div> 345 346 <!-- *********************************************************************** --> 347 <h2><a name="introduction">Introduction</a></h2> 348 <!-- *********************************************************************** --> 349 350 <div> 351 352 <p>The LLVM code representation is designed to be used in three different forms: 353 as an in-memory compiler IR, as an on-disk bitcode representation (suitable 354 for fast loading by a Just-In-Time compiler), and as a human readable 355 assembly language representation. This allows LLVM to provide a powerful 356 intermediate representation for efficient compiler transformations and 357 analysis, while providing a natural means to debug and visualize the 358 transformations. The three different forms of LLVM are all equivalent. This 359 document describes the human readable representation and notation.</p> 360 361 <p>The LLVM representation aims to be light-weight and low-level while being 362 expressive, typed, and extensible at the same time. It aims to be a 363 "universal IR" of sorts, by being at a low enough level that high-level ideas 364 may be cleanly mapped to it (similar to how microprocessors are "universal 365 IR's", allowing many source languages to be mapped to them). By providing 366 type information, LLVM can be used as the target of optimizations: for 367 example, through pointer analysis, it can be proven that a C automatic 368 variable is never accessed outside of the current function, allowing it to 369 be promoted to a simple SSA value instead of a memory location.</p> 370 371 <!-- _______________________________________________________________________ --> 372 <h4> 373 <a name="wellformed">Well-Formedness</a> 374 </h4> 375 376 <div> 377 378 <p>It is important to note that this document describes 'well formed' LLVM 379 assembly language. There is a difference between what the parser accepts and 380 what is considered 'well formed'. For example, the following instruction is 381 syntactically okay, but not well formed:</p> 382 383 <pre class="doc_code"> 384 %x = <a href="#i_add">add</a> i32 1, %x 385 </pre> 386 387 <p>because the definition of <tt>%x</tt> does not dominate all of its uses. The 388 LLVM infrastructure provides a verification pass that may be used to verify 389 that an LLVM module is well formed. This pass is automatically run by the 390 parser after parsing input assembly and by the optimizer before it outputs 391 bitcode. The violations pointed out by the verifier pass indicate bugs in 392 transformation passes or input to the parser.</p> 393 394 </div> 395 396 </div> 397 398 <!-- Describe the typesetting conventions here. --> 399 400 <!-- *********************************************************************** --> 401 <h2><a name="identifiers">Identifiers</a></h2> 402 <!-- *********************************************************************** --> 403 404 <div> 405 406 <p>LLVM identifiers come in two basic types: global and local. Global 407 identifiers (functions, global variables) begin with the <tt>'@'</tt> 408 character. Local identifiers (register names, types) begin with 409 the <tt>'%'</tt> character. Additionally, there are three different formats 410 for identifiers, for different purposes:</p> 411 412 <ol> 413 <li>Named values are represented as a string of characters with their prefix. 414 For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>, 415 <tt>%a.really.long.identifier</tt>. The actual regular expression used is 416 '<tt>[%@][a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. Identifiers which require 417 other characters in their names can be surrounded with quotes. Special 418 characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the 419 ASCII code for the character in hexadecimal. In this way, any character 420 can be used in a name value, even quotes themselves.</li> 421 422 <li>Unnamed values are represented as an unsigned numeric value with their 423 prefix. For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li> 424 425 <li>Constants, which are described in a <a href="#constants">section about 426 constants</a>, below.</li> 427 </ol> 428 429 <p>LLVM requires that values start with a prefix for two reasons: Compilers 430 don't need to worry about name clashes with reserved words, and the set of 431 reserved words may be expanded in the future without penalty. Additionally, 432 unnamed identifiers allow a compiler to quickly come up with a temporary 433 variable without having to avoid symbol table conflicts.</p> 434 435 <p>Reserved words in LLVM are very similar to reserved words in other 436 languages. There are keywords for different opcodes 437 ('<tt><a href="#i_add">add</a></tt>', 438 '<tt><a href="#i_bitcast">bitcast</a></tt>', 439 '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names 440 ('<tt><a href="#t_void">void</a></tt>', 441 '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others. These 442 reserved words cannot conflict with variable names, because none of them 443 start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p> 444 445 <p>Here is an example of LLVM code to multiply the integer variable 446 '<tt>%X</tt>' by 8:</p> 447 448 <p>The easy way:</p> 449 450 <pre class="doc_code"> 451 %result = <a href="#i_mul">mul</a> i32 %X, 8 452 </pre> 453 454 <p>After strength reduction:</p> 455 456 <pre class="doc_code"> 457 %result = <a href="#i_shl">shl</a> i32 %X, i8 3 458 </pre> 459 460 <p>And the hard way:</p> 461 462 <pre class="doc_code"> 463 %0 = <a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i> 464 %1 = <a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i> 465 %result = <a href="#i_add">add</a> i32 %1, %1 466 </pre> 467 468 <p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important 469 lexical features of LLVM:</p> 470 471 <ol> 472 <li>Comments are delimited with a '<tt>;</tt>' and go until the end of 473 line.</li> 474 475 <li>Unnamed temporaries are created when the result of a computation is not 476 assigned to a named value.</li> 477 478 <li>Unnamed temporaries are numbered sequentially</li> 479 </ol> 480 481 <p>It also shows a convention that we follow in this document. When 482 demonstrating instructions, we will follow an instruction with a comment that 483 defines the type and name of value produced. Comments are shown in italic 484 text.</p> 485 486 </div> 487 488 <!-- *********************************************************************** --> 489 <h2><a name="highlevel">High Level Structure</a></h2> 490 <!-- *********************************************************************** --> 491 <div> 492 <!-- ======================================================================= --> 493 <h3> 494 <a name="modulestructure">Module Structure</a> 495 </h3> 496 497 <div> 498 499 <p>LLVM programs are composed of "Module"s, each of which is a translation unit 500 of the input programs. Each module consists of functions, global variables, 501 and symbol table entries. Modules may be combined together with the LLVM 502 linker, which merges function (and global variable) definitions, resolves 503 forward declarations, and merges symbol table entries. Here is an example of 504 the "hello world" module:</p> 505 506 <pre class="doc_code"> 507 <i>; Declare the string constant as a global constant.</i> 508 <a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" <i>; [13 x i8]*</i> 509 510 <i>; External declaration of the puts function</i> 511 <a href="#functionstructure">declare</a> i32 @puts(i8*) <i>; i32 (i8*)* </i> 512 513 <i>; Definition of main function</i> 514 define i32 @main() { <i>; i32()* </i> 515 <i>; Convert [13 x i8]* to i8 *...</i> 516 %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0 <i>; i8*</i> 517 518 <i>; Call puts function to write out the string to stdout.</i> 519 <a href="#i_call">call</a> i32 @puts(i8* %cast210) <i>; i32</i> 520 <a href="#i_ret">ret</a> i32 0 521 } 522 523 <i>; Named metadata</i> 524 !1 = metadata !{i32 41} 525 !foo = !{!1, null} 526 </pre> 527 528 <p>This example is made up of a <a href="#globalvars">global variable</a> named 529 "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, 530 a <a href="#functionstructure">function definition</a> for 531 "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a> 532 "<tt>foo"</tt>.</p> 533 534 <p>In general, a module is made up of a list of global values, where both 535 functions and global variables are global values. Global values are 536 represented by a pointer to a memory location (in this case, a pointer to an 537 array of char, and a pointer to a function), and have one of the 538 following <a href="#linkage">linkage types</a>.</p> 539 540 </div> 541 542 <!-- ======================================================================= --> 543 <h3> 544 <a name="linkage">Linkage Types</a> 545 </h3> 546 547 <div> 548 549 <p>All Global Variables and Functions have one of the following types of 550 linkage:</p> 551 552 <dl> 553 <dt><tt><b><a name="linkage_private">private</a></b></tt></dt> 554 <dd>Global values with "<tt>private</tt>" linkage are only directly accessible 555 by objects in the current module. In particular, linking code into a 556 module with an private global value may cause the private to be renamed as 557 necessary to avoid collisions. Because the symbol is private to the 558 module, all references can be updated. This doesn't show up in any symbol 559 table in the object file.</dd> 560 561 <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt></dt> 562 <dd>Similar to <tt>private</tt>, but the symbol is passed through the 563 assembler and evaluated by the linker. Unlike normal strong symbols, they 564 are removed by the linker from the final linked image (executable or 565 dynamic library).</dd> 566 567 <dt><tt><b><a name="linkage_linker_private_weak">linker_private_weak</a></b></tt></dt> 568 <dd>Similar to "<tt>linker_private</tt>", but the symbol is weak. Note that 569 <tt>linker_private_weak</tt> symbols are subject to coalescing by the 570 linker. The symbols are removed by the linker from the final linked image 571 (executable or dynamic library).</dd> 572 573 <dt><tt><b><a name="linkage_linker_private_weak_def_auto">linker_private_weak_def_auto</a></b></tt></dt> 574 <dd>Similar to "<tt>linker_private_weak</tt>", but it's known that the address 575 of the object is not taken. For instance, functions that had an inline 576 definition, but the compiler decided not to inline it. Note, 577 unlike <tt>linker_private</tt> and <tt>linker_private_weak</tt>, 578 <tt>linker_private_weak_def_auto</tt> may have only <tt>default</tt> 579 visibility. The symbols are removed by the linker from the final linked 580 image (executable or dynamic library).</dd> 581 582 <dt><tt><b><a name="linkage_internal">internal</a></b></tt></dt> 583 <dd>Similar to private, but the value shows as a local symbol 584 (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This 585 corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd> 586 587 <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt></dt> 588 <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted 589 into the object file corresponding to the LLVM module. They exist to 590 allow inlining and other optimizations to take place given knowledge of 591 the definition of the global, which is known to be somewhere outside the 592 module. Globals with <tt>available_externally</tt> linkage are allowed to 593 be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>. 594 This linkage type is only allowed on definitions, not declarations.</dd> 595 596 <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt></dt> 597 <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of 598 the same name when linkage occurs. This can be used to implement 599 some forms of inline functions, templates, or other code which must be 600 generated in each translation unit that uses it, but where the body may 601 be overridden with a more definitive definition later. Unreferenced 602 <tt>linkonce</tt> globals are allowed to be discarded. Note that 603 <tt>linkonce</tt> linkage does not actually allow the optimizer to 604 inline the body of this function into callers because it doesn't know if 605 this definition of the function is the definitive definition within the 606 program or whether it will be overridden by a stronger definition. 607 To enable inlining and other optimizations, use "<tt>linkonce_odr</tt>" 608 linkage.</dd> 609 610 <dt><tt><b><a name="linkage_weak">weak</a></b></tt></dt> 611 <dd>"<tt>weak</tt>" linkage has the same merging semantics as 612 <tt>linkonce</tt> linkage, except that unreferenced globals with 613 <tt>weak</tt> linkage may not be discarded. This is used for globals that 614 are declared "weak" in C source code.</dd> 615 616 <dt><tt><b><a name="linkage_common">common</a></b></tt></dt> 617 <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but 618 they are used for tentative definitions in C, such as "<tt>int X;</tt>" at 619 global scope. 620 Symbols with "<tt>common</tt>" linkage are merged in the same way as 621 <tt>weak symbols</tt>, and they may not be deleted if unreferenced. 622 <tt>common</tt> symbols may not have an explicit section, 623 must have a zero initializer, and may not be marked '<a 624 href="#globalvars"><tt>constant</tt></a>'. Functions and aliases may not 625 have common linkage.</dd> 626 627 628 <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt> 629 <dd>"<tt>appending</tt>" linkage may only be applied to global variables of 630 pointer to array type. When two global variables with appending linkage 631 are linked together, the two global arrays are appended together. This is 632 the LLVM, typesafe, equivalent of having the system linker append together 633 "sections" with identical names when .o files are linked.</dd> 634 635 <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt></dt> 636 <dd>The semantics of this linkage follow the ELF object file model: the symbol 637 is weak until linked, if not linked, the symbol becomes null instead of 638 being an undefined reference.</dd> 639 640 <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt></dt> 641 <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt></dt> 642 <dd>Some languages allow differing globals to be merged, such as two functions 643 with different semantics. Other languages, such as <tt>C++</tt>, ensure 644 that only equivalent globals are ever merged (the "one definition rule" 645 — "ODR"). Such languages can use the <tt>linkonce_odr</tt> 646 and <tt>weak_odr</tt> linkage types to indicate that the global will only 647 be merged with equivalent globals. These linkage types are otherwise the 648 same as their non-<tt>odr</tt> versions.</dd> 649 650 <dt><tt><b><a name="linkage_external">external</a></b></tt>:</dt> 651 <dd>If none of the above identifiers are used, the global is externally 652 visible, meaning that it participates in linkage and can be used to 653 resolve external symbol references.</dd> 654 </dl> 655 656 <p>The next two types of linkage are targeted for Microsoft Windows platform 657 only. They are designed to support importing (exporting) symbols from (to) 658 DLLs (Dynamic Link Libraries).</p> 659 660 <dl> 661 <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt> 662 <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function 663 or variable via a global pointer to a pointer that is set up by the DLL 664 exporting the symbol. On Microsoft Windows targets, the pointer name is 665 formed by combining <code>__imp_</code> and the function or variable 666 name.</dd> 667 668 <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt></dt> 669 <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global 670 pointer to a pointer in a DLL, so that it can be referenced with the 671 <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer 672 name is formed by combining <code>__imp_</code> and the function or 673 variable name.</dd> 674 </dl> 675 676 <p>For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if 677 another module defined a "<tt>.LC0</tt>" variable and was linked with this 678 one, one of the two would be renamed, preventing a collision. Since 679 "<tt>main</tt>" and "<tt>puts</tt>" are external (i.e., lacking any linkage 680 declarations), they are accessible outside of the current module.</p> 681 682 <p>It is illegal for a function <i>declaration</i> to have any linkage type 683 other than <tt>external</tt>, <tt>dllimport</tt> 684 or <tt>extern_weak</tt>.</p> 685 686 <p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt> 687 or <tt>weak_odr</tt> linkages.</p> 688 689 </div> 690 691 <!-- ======================================================================= --> 692 <h3> 693 <a name="callingconv">Calling Conventions</a> 694 </h3> 695 696 <div> 697 698 <p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a> 699 and <a href="#i_invoke">invokes</a> can all have an optional calling 700 convention specified for the call. The calling convention of any pair of 701 dynamic caller/callee must match, or the behavior of the program is 702 undefined. The following calling conventions are supported by LLVM, and more 703 may be added in the future:</p> 704 705 <dl> 706 <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt> 707 <dd>This calling convention (the default if no other calling convention is 708 specified) matches the target C calling conventions. This calling 709 convention supports varargs function calls and tolerates some mismatch in 710 the declared prototype and implemented declaration of the function (as 711 does normal C).</dd> 712 713 <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt> 714 <dd>This calling convention attempts to make calls as fast as possible 715 (e.g. by passing things in registers). This calling convention allows the 716 target to use whatever tricks it wants to produce fast code for the 717 target, without having to conform to an externally specified ABI 718 (Application Binary Interface). 719 <a href="CodeGenerator.html#tailcallopt">Tail calls can only be optimized 720 when this or the GHC convention is used.</a> This calling convention 721 does not support varargs and requires the prototype of all callees to 722 exactly match the prototype of the function definition.</dd> 723 724 <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt> 725 <dd>This calling convention attempts to make code in the caller as efficient 726 as possible under the assumption that the call is not commonly executed. 727 As such, these calls often preserve all registers so that the call does 728 not break any live ranges in the caller side. This calling convention 729 does not support varargs and requires the prototype of all callees to 730 exactly match the prototype of the function definition.</dd> 731 732 <dt><b>"<tt>cc <em>10</em></tt>" - GHC convention</b>:</dt> 733 <dd>This calling convention has been implemented specifically for use by the 734 <a href="http://www.haskell.org/ghc">Glasgow Haskell Compiler (GHC)</a>. 735 It passes everything in registers, going to extremes to achieve this by 736 disabling callee save registers. This calling convention should not be 737 used lightly but only for specific situations such as an alternative to 738 the <em>register pinning</em> performance technique often used when 739 implementing functional programming languages.At the moment only X86 740 supports this convention and it has the following limitations: 741 <ul> 742 <li>On <em>X86-32</em> only supports up to 4 bit type parameters. No 743 floating point types are supported.</li> 744 <li>On <em>X86-64</em> only supports up to 10 bit type parameters and 745 6 floating point parameters.</li> 746 </ul> 747 This calling convention supports 748 <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> but 749 requires both the caller and callee are using it. 750 </dd> 751 752 <dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt> 753 <dd>Any calling convention may be specified by number, allowing 754 target-specific calling conventions to be used. Target specific calling 755 conventions start at 64.</dd> 756 </dl> 757 758 <p>More calling conventions can be added/defined on an as-needed basis, to 759 support Pascal conventions or any other well-known target-independent 760 convention.</p> 761 762 </div> 763 764 <!-- ======================================================================= --> 765 <h3> 766 <a name="visibility">Visibility Styles</a> 767 </h3> 768 769 <div> 770 771 <p>All Global Variables and Functions have one of the following visibility 772 styles:</p> 773 774 <dl> 775 <dt><b>"<tt>default</tt>" - Default style</b>:</dt> 776 <dd>On targets that use the ELF object file format, default visibility means 777 that the declaration is visible to other modules and, in shared libraries, 778 means that the declared entity may be overridden. On Darwin, default 779 visibility means that the declaration is visible to other modules. Default 780 visibility corresponds to "external linkage" in the language.</dd> 781 782 <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt> 783 <dd>Two declarations of an object with hidden visibility refer to the same 784 object if they are in the same shared object. Usually, hidden visibility 785 indicates that the symbol will not be placed into the dynamic symbol 786 table, so no other module (executable or shared library) can reference it 787 directly.</dd> 788 789 <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt> 790 <dd>On ELF, protected visibility indicates that the symbol will be placed in 791 the dynamic symbol table, but that references within the defining module 792 will bind to the local symbol. That is, the symbol cannot be overridden by 793 another module.</dd> 794 </dl> 795 796 </div> 797 798 <!-- ======================================================================= --> 799 <h3> 800 <a name="namedtypes">Named Types</a> 801 </h3> 802 803 <div> 804 805 <p>LLVM IR allows you to specify name aliases for certain types. This can make 806 it easier to read the IR and make the IR more condensed (particularly when 807 recursive types are involved). An example of a name specification is:</p> 808 809 <pre class="doc_code"> 810 %mytype = type { %mytype*, i32 } 811 </pre> 812 813 <p>You may give a name to any <a href="#typesystem">type</a> except 814 "<a href="#t_void">void</a>". Type name aliases may be used anywhere a type 815 is expected with the syntax "%mytype".</p> 816 817 <p>Note that type names are aliases for the structural type that they indicate, 818 and that you can therefore specify multiple names for the same type. This 819 often leads to confusing behavior when dumping out a .ll file. Since LLVM IR 820 uses structural typing, the name is not part of the type. When printing out 821 LLVM IR, the printer will pick <em>one name</em> to render all types of a 822 particular shape. This means that if you have code where two different 823 source types end up having the same LLVM type, that the dumper will sometimes 824 print the "wrong" or unexpected type. This is an important design point and 825 isn't going to change.</p> 826 827 </div> 828 829 <!-- ======================================================================= --> 830 <h3> 831 <a name="globalvars">Global Variables</a> 832 </h3> 833 834 <div> 835 836 <p>Global variables define regions of memory allocated at compilation time 837 instead of run-time. Global variables may optionally be initialized, may 838 have an explicit section to be placed in, and may have an optional explicit 839 alignment specified. A variable may be defined as "thread_local", which 840 means that it will not be shared by threads (each thread will have a 841 separated copy of the variable). A variable may be defined as a global 842 "constant," which indicates that the contents of the variable 843 will <b>never</b> be modified (enabling better optimization, allowing the 844 global data to be placed in the read-only section of an executable, etc). 845 Note that variables that need runtime initialization cannot be marked 846 "constant" as there is a store to the variable.</p> 847 848 <p>LLVM explicitly allows <em>declarations</em> of global variables to be marked 849 constant, even if the final definition of the global is not. This capability 850 can be used to enable slightly better optimization of the program, but 851 requires the language definition to guarantee that optimizations based on the 852 'constantness' are valid for the translation units that do not include the 853 definition.</p> 854 855 <p>As SSA values, global variables define pointer values that are in scope 856 (i.e. they dominate) all basic blocks in the program. Global variables 857 always define a pointer to their "content" type because they describe a 858 region of memory, and all memory objects in LLVM are accessed through 859 pointers.</p> 860 861 <p>Global variables can be marked with <tt>unnamed_addr</tt> which indicates 862 that the address is not significant, only the content. Constants marked 863 like this can be merged with other constants if they have the same 864 initializer. Note that a constant with significant address <em>can</em> 865 be merged with a <tt>unnamed_addr</tt> constant, the result being a 866 constant whose address is significant.</p> 867 868 <p>A global variable may be declared to reside in a target-specific numbered 869 address space. For targets that support them, address spaces may affect how 870 optimizations are performed and/or what target instructions are used to 871 access the variable. The default address space is zero. The address space 872 qualifier must precede any other attributes.</p> 873 874 <p>LLVM allows an explicit section to be specified for globals. If the target 875 supports it, it will emit globals to the section specified.</p> 876 877 <p>An explicit alignment may be specified for a global, which must be a power 878 of 2. If not present, or if the alignment is set to zero, the alignment of 879 the global is set by the target to whatever it feels convenient. If an 880 explicit alignment is specified, the global is forced to have exactly that 881 alignment. Targets and optimizers are not allowed to over-align the global 882 if the global has an assigned section. In this case, the extra alignment 883 could be observable: for example, code could assume that the globals are 884 densely packed in their section and try to iterate over them as an array, 885 alignment padding would break this iteration.</p> 886 887 <p>For example, the following defines a global in a numbered address space with 888 an initializer, section, and alignment:</p> 889 890 <pre class="doc_code"> 891 @G = addrspace(5) constant float 1.0, section "foo", align 4 892 </pre> 893 894 </div> 895 896 897 <!-- ======================================================================= --> 898 <h3> 899 <a name="functionstructure">Functions</a> 900 </h3> 901 902 <div> 903 904 <p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an 905 optional <a href="#linkage">linkage type</a>, an optional 906 <a href="#visibility">visibility style</a>, an optional 907 <a href="#callingconv">calling convention</a>, 908 an optional <tt>unnamed_addr</tt> attribute, a return type, an optional 909 <a href="#paramattrs">parameter attribute</a> for the return type, a function 910 name, a (possibly empty) argument list (each with optional 911 <a href="#paramattrs">parameter attributes</a>), optional 912 <a href="#fnattrs">function attributes</a>, an optional section, an optional 913 alignment, an optional <a href="#gc">garbage collector name</a>, an opening 914 curly brace, a list of basic blocks, and a closing curly brace.</p> 915 916 <p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an 917 optional <a href="#linkage">linkage type</a>, an optional 918 <a href="#visibility">visibility style</a>, an optional 919 <a href="#callingconv">calling convention</a>, 920 an optional <tt>unnamed_addr</tt> attribute, a return type, an optional 921 <a href="#paramattrs">parameter attribute</a> for the return type, a function 922 name, a possibly empty list of arguments, an optional alignment, and an 923 optional <a href="#gc">garbage collector name</a>.</p> 924 925 <p>A function definition contains a list of basic blocks, forming the CFG 926 (Control Flow Graph) for the function. Each basic block may optionally start 927 with a label (giving the basic block a symbol table entry), contains a list 928 of instructions, and ends with a <a href="#terminators">terminator</a> 929 instruction (such as a branch or function return).</p> 930 931 <p>The first basic block in a function is special in two ways: it is immediately 932 executed on entrance to the function, and it is not allowed to have 933 predecessor basic blocks (i.e. there can not be any branches to the entry 934 block of a function). Because the block can have no predecessors, it also 935 cannot have any <a href="#i_phi">PHI nodes</a>.</p> 936 937 <p>LLVM allows an explicit section to be specified for functions. If the target 938 supports it, it will emit functions to the section specified.</p> 939 940 <p>An explicit alignment may be specified for a function. If not present, or if 941 the alignment is set to zero, the alignment of the function is set by the 942 target to whatever it feels convenient. If an explicit alignment is 943 specified, the function is forced to have at least that much alignment. All 944 alignments must be a power of 2.</p> 945 946 <p>If the <tt>unnamed_addr</tt> attribute is given, the address is know to not 947 be significant and two identical functions can be merged</p>. 948 949 <h5>Syntax:</h5> 950 <pre class="doc_code"> 951 define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>] 952 [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] 953 <ResultType> @<FunctionName> ([argument list]) 954 [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N] 955 [<a href="#gc">gc</a>] { ... } 956 </pre> 957 958 </div> 959 960 <!-- ======================================================================= --> 961 <h3> 962 <a name="aliasstructure">Aliases</a> 963 </h3> 964 965 <div> 966 967 <p>Aliases act as "second name" for the aliasee value (which can be either 968 function, global variable, another alias or bitcast of global value). Aliases 969 may have an optional <a href="#linkage">linkage type</a>, and an 970 optional <a href="#visibility">visibility style</a>.</p> 971 972 <h5>Syntax:</h5> 973 <pre class="doc_code"> 974 @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee> 975 </pre> 976 977 </div> 978 979 <!-- ======================================================================= --> 980 <h3> 981 <a name="namedmetadatastructure">Named Metadata</a> 982 </h3> 983 984 <div> 985 986 <p>Named metadata is a collection of metadata. <a href="#metadata">Metadata 987 nodes</a> (but not metadata strings) are the only valid operands for 988 a named metadata.</p> 989 990 <h5>Syntax:</h5> 991 <pre class="doc_code"> 992 ; Some unnamed metadata nodes, which are referenced by the named metadata. 993 !0 = metadata !{metadata !"zero"} 994 !1 = metadata !{metadata !"one"} 995 !2 = metadata !{metadata !"two"} 996 ; A named metadata. 997 !name = !{!0, !1, !2} 998 </pre> 999 1000 </div> 1001 1002 <!-- ======================================================================= --> 1003 <h3> 1004 <a name="paramattrs">Parameter Attributes</a> 1005 </h3> 1006 1007 <div> 1008 1009 <p>The return type and each parameter of a function type may have a set of 1010 <i>parameter attributes</i> associated with them. Parameter attributes are 1011 used to communicate additional information about the result or parameters of 1012 a function. Parameter attributes are considered to be part of the function, 1013 not of the function type, so functions with different parameter attributes 1014 can have the same function type.</p> 1015 1016 <p>Parameter attributes are simple keywords that follow the type specified. If 1017 multiple parameter attributes are needed, they are space separated. For 1018 example:</p> 1019 1020 <pre class="doc_code"> 1021 declare i32 @printf(i8* noalias nocapture, ...) 1022 declare i32 @atoi(i8 zeroext) 1023 declare signext i8 @returns_signed_char() 1024 </pre> 1025 1026 <p>Note that any attributes for the function result (<tt>nounwind</tt>, 1027 <tt>readonly</tt>) come immediately after the argument list.</p> 1028 1029 <p>Currently, only the following parameter attributes are defined:</p> 1030 1031 <dl> 1032 <dt><tt><b>zeroext</b></tt></dt> 1033 <dd>This indicates to the code generator that the parameter or return value 1034 should be zero-extended to the extent required by the target's ABI (which 1035 is usually 32-bits, but is 8-bits for a i1 on x86-64) by the caller (for a 1036 parameter) or the callee (for a return value).</dd> 1037 1038 <dt><tt><b>signext</b></tt></dt> 1039 <dd>This indicates to the code generator that the parameter or return value 1040 should be sign-extended to the extent required by the target's ABI (which 1041 is usually 32-bits) by the caller (for a parameter) or the callee (for a 1042 return value).</dd> 1043 1044 <dt><tt><b>inreg</b></tt></dt> 1045 <dd>This indicates that this parameter or return value should be treated in a 1046 special target-dependent fashion during while emitting code for a function 1047 call or return (usually, by putting it in a register as opposed to memory, 1048 though some targets use it to distinguish between two different kinds of 1049 registers). Use of this attribute is target-specific.</dd> 1050 1051 <dt><tt><b><a name="byval">byval</a></b></tt></dt> 1052 <dd><p>This indicates that the pointer parameter should really be passed by 1053 value to the function. The attribute implies that a hidden copy of the 1054 pointee 1055 is made between the caller and the callee, so the callee is unable to 1056 modify the value in the callee. This attribute is only valid on LLVM 1057 pointer arguments. It is generally used to pass structs and arrays by 1058 value, but is also valid on pointers to scalars. The copy is considered 1059 to belong to the caller not the callee (for example, 1060 <tt><a href="#readonly">readonly</a></tt> functions should not write to 1061 <tt>byval</tt> parameters). This is not a valid attribute for return 1062 values.</p> 1063 1064 <p>The byval attribute also supports specifying an alignment with 1065 the align attribute. It indicates the alignment of the stack slot to 1066 form and the known alignment of the pointer specified to the call site. If 1067 the alignment is not specified, then the code generator makes a 1068 target-specific assumption.</p></dd> 1069 1070 <dt><tt><b><a name="sret">sret</a></b></tt></dt> 1071 <dd>This indicates that the pointer parameter specifies the address of a 1072 structure that is the return value of the function in the source program. 1073 This pointer must be guaranteed by the caller to be valid: loads and 1074 stores to the structure may be assumed by the callee to not to trap. This 1075 may only be applied to the first parameter. This is not a valid attribute 1076 for return values. </dd> 1077 1078 <dt><tt><b><a name="noalias">noalias</a></b></tt></dt> 1079 <dd>This indicates that pointer values 1080 <a href="#pointeraliasing"><i>based</i></a> on the argument or return 1081 value do not alias pointer values which are not <i>based</i> on it, 1082 ignoring certain "irrelevant" dependencies. 1083 For a call to the parent function, dependencies between memory 1084 references from before or after the call and from those during the call 1085 are "irrelevant" to the <tt>noalias</tt> keyword for the arguments and 1086 return value used in that call. 1087 The caller shares the responsibility with the callee for ensuring that 1088 these requirements are met. 1089 For further details, please see the discussion of the NoAlias response in 1090 <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.<br> 1091 <br> 1092 Note that this definition of <tt>noalias</tt> is intentionally 1093 similar to the definition of <tt>restrict</tt> in C99 for function 1094 arguments, though it is slightly weaker. 1095 <br> 1096 For function return values, C99's <tt>restrict</tt> is not meaningful, 1097 while LLVM's <tt>noalias</tt> is. 1098 </dd> 1099 1100 <dt><tt><b><a name="nocapture">nocapture</a></b></tt></dt> 1101 <dd>This indicates that the callee does not make any copies of the pointer 1102 that outlive the callee itself. This is not a valid attribute for return 1103 values.</dd> 1104 1105 <dt><tt><b><a name="nest">nest</a></b></tt></dt> 1106 <dd>This indicates that the pointer parameter can be excised using the 1107 <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid 1108 attribute for return values.</dd> 1109 </dl> 1110 1111 </div> 1112 1113 <!-- ======================================================================= --> 1114 <h3> 1115 <a name="gc">Garbage Collector Names</a> 1116 </h3> 1117 1118 <div> 1119 1120 <p>Each function may specify a garbage collector name, which is simply a 1121 string:</p> 1122 1123 <pre class="doc_code"> 1124 define void @f() gc "name" { ... } 1125 </pre> 1126 1127 <p>The compiler declares the supported values of <i>name</i>. Specifying a 1128 collector which will cause the compiler to alter its output in order to 1129 support the named garbage collection algorithm.</p> 1130 1131 </div> 1132 1133 <!-- ======================================================================= --> 1134 <h3> 1135 <a name="fnattrs">Function Attributes</a> 1136 </h3> 1137 1138 <div> 1139 1140 <p>Function attributes are set to communicate additional information about a 1141 function. Function attributes are considered to be part of the function, not 1142 of the function type, so functions with different parameter attributes can 1143 have the same function type.</p> 1144 1145 <p>Function attributes are simple keywords that follow the type specified. If 1146 multiple attributes are needed, they are space separated. For example:</p> 1147 1148 <pre class="doc_code"> 1149 define void @f() noinline { ... } 1150 define void @f() alwaysinline { ... } 1151 define void @f() alwaysinline optsize { ... } 1152 define void @f() optsize { ... } 1153 </pre> 1154 1155 <dl> 1156 <dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt> 1157 <dd>This attribute indicates that, when emitting the prologue and epilogue, 1158 the backend should forcibly align the stack pointer. Specify the 1159 desired alignment, which must be a power of two, in parentheses. 1160 1161 <dt><tt><b>alwaysinline</b></tt></dt> 1162 <dd>This attribute indicates that the inliner should attempt to inline this 1163 function into callers whenever possible, ignoring any active inlining size 1164 threshold for this caller.</dd> 1165 1166 <dt><tt><b>nonlazybind</b></tt></dt> 1167 <dd>This attribute suppresses lazy symbol binding for the function. This 1168 may make calls to the function faster, at the cost of extra program 1169 startup time if the function is not called during program startup.</dd> 1170 1171 <dt><tt><b>inlinehint</b></tt></dt> 1172 <dd>This attribute indicates that the source code contained a hint that inlining 1173 this function is desirable (such as the "inline" keyword in C/C++). It 1174 is just a hint; it imposes no requirements on the inliner.</dd> 1175 1176 <dt><tt><b>naked</b></tt></dt> 1177 <dd>This attribute disables prologue / epilogue emission for the function. 1178 This can have very system-specific consequences.</dd> 1179 1180 <dt><tt><b>noimplicitfloat</b></tt></dt> 1181 <dd>This attributes disables implicit floating point instructions.</dd> 1182 1183 <dt><tt><b>noinline</b></tt></dt> 1184 <dd>This attribute indicates that the inliner should never inline this 1185 function in any situation. This attribute may not be used together with 1186 the <tt>alwaysinline</tt> attribute.</dd> 1187 1188 <dt><tt><b>noredzone</b></tt></dt> 1189 <dd>This attribute indicates that the code generator should not use a red 1190 zone, even if the target-specific ABI normally permits it.</dd> 1191 1192 <dt><tt><b>noreturn</b></tt></dt> 1193 <dd>This function attribute indicates that the function never returns 1194 normally. This produces undefined behavior at runtime if the function 1195 ever does dynamically return.</dd> 1196 1197 <dt><tt><b>nounwind</b></tt></dt> 1198 <dd>This function attribute indicates that the function never returns with an 1199 unwind or exceptional control flow. If the function does unwind, its 1200 runtime behavior is undefined.</dd> 1201 1202 <dt><tt><b>optsize</b></tt></dt> 1203 <dd>This attribute suggests that optimization passes and code generator passes 1204 make choices that keep the code size of this function low, and otherwise 1205 do optimizations specifically to reduce code size.</dd> 1206 1207 <dt><tt><b>readnone</b></tt></dt> 1208 <dd>This attribute indicates that the function computes its result (or decides 1209 to unwind an exception) based strictly on its arguments, without 1210 dereferencing any pointer arguments or otherwise accessing any mutable 1211 state (e.g. memory, control registers, etc) visible to caller functions. 1212 It does not write through any pointer arguments 1213 (including <tt><a href="#byval">byval</a></tt> arguments) and never 1214 changes any state visible to callers. This means that it cannot unwind 1215 exceptions by calling the <tt>C++</tt> exception throwing methods, but 1216 could use the <tt>unwind</tt> instruction.</dd> 1217 1218 <dt><tt><b><a name="readonly">readonly</a></b></tt></dt> 1219 <dd>This attribute indicates that the function does not write through any 1220 pointer arguments (including <tt><a href="#byval">byval</a></tt> 1221 arguments) or otherwise modify any state (e.g. memory, control registers, 1222 etc) visible to caller functions. It may dereference pointer arguments 1223 and read state that may be set in the caller. A readonly function always 1224 returns the same value (or unwinds an exception identically) when called 1225 with the same set of arguments and global state. It cannot unwind an 1226 exception by calling the <tt>C++</tt> exception throwing methods, but may 1227 use the <tt>unwind</tt> instruction.</dd> 1228 1229 <dt><tt><b><a name="ssp">ssp</a></b></tt></dt> 1230 <dd>This attribute indicates that the function should emit a stack smashing 1231 protector. It is in the form of a "canary"—a random value placed on 1232 the stack before the local variables that's checked upon return from the 1233 function to see if it has been overwritten. A heuristic is used to 1234 determine if a function needs stack protectors or not.<br> 1235 <br> 1236 If a function that has an <tt>ssp</tt> attribute is inlined into a 1237 function that doesn't have an <tt>ssp</tt> attribute, then the resulting 1238 function will have an <tt>ssp</tt> attribute.</dd> 1239 1240 <dt><tt><b>sspreq</b></tt></dt> 1241 <dd>This attribute indicates that the function should <em>always</em> emit a 1242 stack smashing protector. This overrides 1243 the <tt><a href="#ssp">ssp</a></tt> function attribute.<br> 1244 <br> 1245 If a function that has an <tt>sspreq</tt> attribute is inlined into a 1246 function that doesn't have an <tt>sspreq</tt> attribute or which has 1247 an <tt>ssp</tt> attribute, then the resulting function will have 1248 an <tt>sspreq</tt> attribute.</dd> 1249 1250 <dt><tt><b><a name="uwtable">uwtable</a></b></tt></dt> 1251 <dd>This attribute indicates that the ABI being targeted requires that 1252 an unwind table entry be produce for this function even if we can 1253 show that no exceptions passes by it. This is normally the case for 1254 the ELF x86-64 abi, but it can be disabled for some compilation 1255 units.</dd> 1256 1257 <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt> 1258 <dd>This attribute indicates that this function can return 1259 twice. The C <code>setjmp</code> is an example of such a function. 1260 The compiler disables some optimizations (like tail calls) in the caller of 1261 these functions.</dd> 1262 </dl> 1263 1264 </div> 1265 1266 <!-- ======================================================================= --> 1267 <h3> 1268 <a name="moduleasm">Module-Level Inline Assembly</a> 1269 </h3> 1270 1271 <div> 1272 1273 <p>Modules may contain "module-level inline asm" blocks, which corresponds to 1274 the GCC "file scope inline asm" blocks. These blocks are internally 1275 concatenated by LLVM and treated as a single unit, but may be separated in 1276 the <tt>.ll</tt> file if desired. The syntax is very simple:</p> 1277 1278 <pre class="doc_code"> 1279 module asm "inline asm code goes here" 1280 module asm "more can go here" 1281 </pre> 1282 1283 <p>The strings can contain any character by escaping non-printable characters. 1284 The escape sequence used is simply "\xx" where "xx" is the two digit hex code 1285 for the number.</p> 1286 1287 <p>The inline asm code is simply printed to the machine code .s file when 1288 assembly code is generated.</p> 1289 1290 </div> 1291 1292 <!-- ======================================================================= --> 1293 <h3> 1294 <a name="datalayout">Data Layout</a> 1295 </h3> 1296 1297 <div> 1298 1299 <p>A module may specify a target specific data layout string that specifies how 1300 data is to be laid out in memory. The syntax for the data layout is 1301 simply:</p> 1302 1303 <pre class="doc_code"> 1304 target datalayout = "<i>layout specification</i>" 1305 </pre> 1306 1307 <p>The <i>layout specification</i> consists of a list of specifications 1308 separated by the minus sign character ('-'). Each specification starts with 1309 a letter and may include other information after the letter to define some 1310 aspect of the data layout. The specifications accepted are as follows:</p> 1311 1312 <dl> 1313 <dt><tt>E</tt></dt> 1314 <dd>Specifies that the target lays out data in big-endian form. That is, the 1315 bits with the most significance have the lowest address location.</dd> 1316 1317 <dt><tt>e</tt></dt> 1318 <dd>Specifies that the target lays out data in little-endian form. That is, 1319 the bits with the least significance have the lowest address 1320 location.</dd> 1321 1322 <dt><tt>S<i>size</i></tt></dt> 1323 <dd>Specifies the natural alignment of the stack in bits. Alignment promotion 1324 of stack variables is limited to the natural stack alignment to avoid 1325 dynamic stack realignment. The stack alignment must be a multiple of 1326 8-bits. If omitted, the natural stack alignment defaults to "unspecified", 1327 which does not prevent any alignment promotions.</dd> 1328 1329 <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> 1330 <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and 1331 <i>preferred</i> alignments. All sizes are in bits. Specifying 1332 the <i>pref</i> alignment is optional. If omitted, the 1333 preceding <tt>:</tt> should be omitted too.</dd> 1334 1335 <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> 1336 <dd>This specifies the alignment for an integer type of a given bit 1337 <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd> 1338 1339 <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> 1340 <dd>This specifies the alignment for a vector type of a given bit 1341 <i>size</i>.</dd> 1342 1343 <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> 1344 <dd>This specifies the alignment for a floating point type of a given bit 1345 <i>size</i>. Only values of <i>size</i> that are supported by the target 1346 will work. 32 (float) and 64 (double) are supported on all targets; 1347 80 or 128 (different flavors of long double) are also supported on some 1348 targets. 1349 1350 <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> 1351 <dd>This specifies the alignment for an aggregate type of a given bit 1352 <i>size</i>.</dd> 1353 1354 <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt> 1355 <dd>This specifies the alignment for a stack object of a given bit 1356 <i>size</i>.</dd> 1357 1358 <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt> 1359 <dd>This specifies a set of native integer widths for the target CPU 1360 in bits. For example, it might contain "n32" for 32-bit PowerPC, 1361 "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64. Elements of 1362 this set are considered to support most general arithmetic 1363 operations efficiently.</dd> 1364 </dl> 1365 1366 <p>When constructing the data layout for a given target, LLVM starts with a 1367 default set of specifications which are then (possibly) overridden by the 1368 specifications in the <tt>datalayout</tt> keyword. The default specifications 1369 are given in this list:</p> 1370 1371 <ul> 1372 <li><tt>E</tt> - big endian</li> 1373 <li><tt>p:64:64:64</tt> - 64-bit pointers with 64-bit alignment</li> 1374 <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li> 1375 <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li> 1376 <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li> 1377 <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li> 1378 <li><tt>i64:32:64</tt> - i64 has ABI alignment of 32-bits but preferred 1379 alignment of 64-bits</li> 1380 <li><tt>f32:32:32</tt> - float is 32-bit aligned</li> 1381 <li><tt>f64:64:64</tt> - double is 64-bit aligned</li> 1382 <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li> 1383 <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li> 1384 <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li> 1385 <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li> 1386 </ul> 1387 1388 <p>When LLVM is determining the alignment for a given type, it uses the 1389 following rules:</p> 1390 1391 <ol> 1392 <li>If the type sought is an exact match for one of the specifications, that 1393 specification is used.</li> 1394 1395 <li>If no match is found, and the type sought is an integer type, then the 1396 smallest integer type that is larger than the bitwidth of the sought type 1397 is used. If none of the specifications are larger than the bitwidth then 1398 the the largest integer type is used. For example, given the default 1399 specifications above, the i7 type will use the alignment of i8 (next 1400 largest) while both i65 and i256 will use the alignment of i64 (largest 1401 specified).</li> 1402 1403 <li>If no match is found, and the type sought is a vector type, then the 1404 largest vector type that is smaller than the sought vector type will be 1405 used as a fall back. This happens because <128 x double> can be 1406 implemented in terms of 64 <2 x double>, for example.</li> 1407 </ol> 1408 1409 <p>The function of the data layout string may not be what you expect. Notably, 1410 this is not a specification from the frontend of what alignment the code 1411 generator should use.</p> 1412 1413 <p>Instead, if specified, the target data layout is required to match what the 1414 ultimate <em>code generator</em> expects. This string is used by the 1415 mid-level optimizers to 1416 improve code, and this only works if it matches what the ultimate code 1417 generator uses. If you would like to generate IR that does not embed this 1418 target-specific detail into the IR, then you don't have to specify the 1419 string. This will disable some optimizations that require precise layout 1420 information, but this also prevents those optimizations from introducing 1421 target specificity into the IR.</p> 1422 1423 1424 1425 </div> 1426 1427 <!-- ======================================================================= --> 1428 <h3> 1429 <a name="pointeraliasing">Pointer Aliasing Rules</a> 1430 </h3> 1431 1432 <div> 1433 1434 <p>Any memory access must be done through a pointer value associated 1435 with an address range of the memory access, otherwise the behavior 1436 is undefined. Pointer values are associated with address ranges 1437 according to the following rules:</p> 1438 1439 <ul> 1440 <li>A pointer value is associated with the addresses associated with 1441 any value it is <i>based</i> on. 1442 <li>An address of a global variable is associated with the address 1443 range of the variable's storage.</li> 1444 <li>The result value of an allocation instruction is associated with 1445 the address range of the allocated storage.</li> 1446 <li>A null pointer in the default address-space is associated with 1447 no address.</li> 1448 <li>An integer constant other than zero or a pointer value returned 1449 from a function not defined within LLVM may be associated with address 1450 ranges allocated through mechanisms other than those provided by 1451 LLVM. Such ranges shall not overlap with any ranges of addresses 1452 allocated by mechanisms provided by LLVM.</li> 1453 </ul> 1454 1455 <p>A pointer value is <i>based</i> on another pointer value according 1456 to the following rules:</p> 1457 1458 <ul> 1459 <li>A pointer value formed from a 1460 <tt><a href="#i_getelementptr">getelementptr</a></tt> operation 1461 is <i>based</i> on the first operand of the <tt>getelementptr</tt>.</li> 1462 <li>The result value of a 1463 <tt><a href="#i_bitcast">bitcast</a></tt> is <i>based</i> on the operand 1464 of the <tt>bitcast</tt>.</li> 1465 <li>A pointer value formed by an 1466 <tt><a href="#i_inttoptr">inttoptr</a></tt> is <i>based</i> on all 1467 pointer values that contribute (directly or indirectly) to the 1468 computation of the pointer's value.</li> 1469 <li>The "<i>based</i> on" relationship is transitive.</li> 1470 </ul> 1471 1472 <p>Note that this definition of <i>"based"</i> is intentionally 1473 similar to the definition of <i>"based"</i> in C99, though it is 1474 slightly weaker.</p> 1475 1476 <p>LLVM IR does not associate types with memory. The result type of a 1477 <tt><a href="#i_load">load</a></tt> merely indicates the size and 1478 alignment of the memory from which to load, as well as the 1479 interpretation of the value. The first operand type of a 1480 <tt><a href="#i_store">store</a></tt> similarly only indicates the size 1481 and alignment of the store.</p> 1482 1483 <p>Consequently, type-based alias analysis, aka TBAA, aka 1484 <tt>-fstrict-aliasing</tt>, is not applicable to general unadorned 1485 LLVM IR. <a href="#metadata">Metadata</a> may be used to encode 1486 additional information which specialized optimization passes may use 1487 to implement type-based alias analysis.</p> 1488 1489 </div> 1490 1491 <!-- ======================================================================= --> 1492 <h3> 1493 <a name="volatile">Volatile Memory Accesses</a> 1494 </h3> 1495 1496 <div> 1497 1498 <p>Certain memory accesses, such as <a href="#i_load"><tt>load</tt></a>s, <a 1499 href="#i_store"><tt>store</tt></a>s, and <a 1500 href="#int_memcpy"><tt>llvm.memcpy</tt></a>s may be marked <tt>volatile</tt>. 1501 The optimizers must not change the number of volatile operations or change their 1502 order of execution relative to other volatile operations. The optimizers 1503 <i>may</i> change the order of volatile operations relative to non-volatile 1504 operations. This is not Java's "volatile" and has no cross-thread 1505 synchronization behavior.</p> 1506 1507 </div> 1508 1509 <!-- ======================================================================= --> 1510 <h3> 1511 <a name="memmodel">Memory Model for Concurrent Operations</a> 1512 </h3> 1513 1514 <div> 1515 1516 <p>The LLVM IR does not define any way to start parallel threads of execution 1517 or to register signal handlers. Nonetheless, there are platform-specific 1518 ways to create them, and we define LLVM IR's behavior in their presence. This 1519 model is inspired by the C++0x memory model.</p> 1520 1521 <p>For a more informal introduction to this model, see the 1522 <a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>. 1523 1524 <p>We define a <i>happens-before</i> partial order as the least partial order 1525 that</p> 1526 <ul> 1527 <li>Is a superset of single-thread program order, and</li> 1528 <li>When a <i>synchronizes-with</i> <tt>b</tt>, includes an edge from 1529 <tt>a</tt> to <tt>b</tt>. <i>Synchronizes-with</i> pairs are introduced 1530 by platform-specific techniques, like pthread locks, thread 1531 creation, thread joining, etc., and by atomic instructions. 1532 (See also <a href="#ordering">Atomic Memory Ordering Constraints</a>). 1533 </li> 1534 </ul> 1535 1536 <p>Note that program order does not introduce <i>happens-before</i> edges 1537 between a thread and signals executing inside that thread.</p> 1538 1539 <p>Every (defined) read operation (load instructions, memcpy, atomic 1540 loads/read-modify-writes, etc.) <var>R</var> reads a series of bytes written by 1541 (defined) write operations (store instructions, atomic 1542 stores/read-modify-writes, memcpy, etc.). For the purposes of this section, 1543 initialized globals are considered to have a write of the initializer which is 1544 atomic and happens before any other read or write of the memory in question. 1545 For each byte of a read <var>R</var>, <var>R<sub>byte</sub></var> may see 1546 any write to the same byte, except:</p> 1547 1548 <ul> 1549 <li>If <var>write<sub>1</sub></var> happens before 1550 <var>write<sub>2</sub></var>, and <var>write<sub>2</sub></var> happens 1551 before <var>R<sub>byte</sub></var>, then <var>R<sub>byte</sub></var> 1552 does not see <var>write<sub>1</sub></var>. 1553 <li>If <var>R<sub>byte</sub></var> happens before 1554 <var>write<sub>3</sub></var>, then <var>R<sub>byte</sub></var> does not 1555 see <var>write<sub>3</sub></var>. 1556 </ul> 1557 1558 <p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows: 1559 <ul> 1560 <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile 1561 is supposed to give guarantees which can support 1562 <code>sig_atomic_t</code> in C/C++, and may be used for accesses to 1563 addresses which do not behave like normal memory. It does not generally 1564 provide cross-thread synchronization.) 1565 <li>Otherwise, if there is no write to the same byte that happens before 1566 <var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns 1567 <tt>undef</tt> for that byte. 1568 <li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write, 1569 <var>R<sub>byte</sub></var> returns the value written by that 1570 write.</li> 1571 <li>Otherwise, if <var>R</var> is atomic, and all the writes 1572 <var>R<sub>byte</sub></var> may see are atomic, it chooses one of the 1573 values written. See the <a href="#ordering">Atomic Memory Ordering 1574 Constraints</a> section for additional constraints on how the choice 1575 is made. 1576 <li>Otherwise <var>R<sub>byte</sub></var> returns <tt>undef</tt>.</li> 1577 </ul> 1578 1579 <p><var>R</var> returns the value composed of the series of bytes it read. 1580 This implies that some bytes within the value may be <tt>undef</tt> 1581 <b>without</b> the entire value being <tt>undef</tt>. Note that this only 1582 defines the semantics of the operation; it doesn't mean that targets will 1583 emit more than one instruction to read the series of bytes.</p> 1584 1585 <p>Note that in cases where none of the atomic intrinsics are used, this model 1586 places only one restriction on IR transformations on top of what is required 1587 for single-threaded execution: introducing a store to a byte which might not 1588 otherwise be stored is not allowed in general. (Specifically, in the case 1589 where another thread might write to and read from an address, introducing a 1590 store can change a load that may see exactly one write into a load that may 1591 see multiple writes.)</p> 1592 1593 <!-- FIXME: This model assumes all targets where concurrency is relevant have 1594 a byte-size store which doesn't affect adjacent bytes. As far as I can tell, 1595 none of the backends currently in the tree fall into this category; however, 1596 there might be targets which care. If there are, we want a paragraph 1597 like the following: 1598 1599 Targets may specify that stores narrower than a certain width are not 1600 available; on such a target, for the purposes of this model, treat any 1601 non-atomic write with an alignment or width less than the minimum width 1602 as if it writes to the relevant surrounding bytes. 1603 --> 1604 1605 </div> 1606 1607 <!-- ======================================================================= --> 1608 <h3> 1609 <a name="ordering">Atomic Memory Ordering Constraints</a> 1610 </h3> 1611 1612 <div> 1613 1614 <p>Atomic instructions (<a href="#i_cmpxchg"><code>cmpxchg</code></a>, 1615 <a href="#i_atomicrmw"><code>atomicrmw</code></a>, 1616 <a href="#i_fence"><code>fence</code></a>, 1617 <a href="#i_load"><code>atomic load</code></a>, and 1618 <a href="#i_store"><code>atomic store</code></a>) take an ordering parameter 1619 that determines which other atomic instructions on the same address they 1620 <i>synchronize with</i>. These semantics are borrowed from Java and C++0x, 1621 but are somewhat more colloquial. If these descriptions aren't precise enough, 1622 check those specs (see spec references in the 1623 <a href="Atomic.html#introduction">atomics guide</a>). 1624 <a href="#i_fence"><code>fence</code></a> instructions 1625 treat these orderings somewhat differently since they don't take an address. 1626 See that instruction's documentation for details.</p> 1627 1628 <p>For a simpler introduction to the ordering constraints, see the 1629 <a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p> 1630 1631 <dl> 1632 <dt><code>unordered</code></dt> 1633 <dd>The set of values that can be read is governed by the happens-before 1634 partial order. A value cannot be read unless some operation wrote it. 1635 This is intended to provide a guarantee strong enough to model Java's 1636 non-volatile shared variables. This ordering cannot be specified for 1637 read-modify-write operations; it is not strong enough to make them atomic 1638 in any interesting way.</dd> 1639 <dt><code>monotonic</code></dt> 1640 <dd>In addition to the guarantees of <code>unordered</code>, there is a single 1641 total order for modifications by <code>monotonic</code> operations on each 1642 address. All modification orders must be compatible with the happens-before 1643 order. There is no guarantee that the modification orders can be combined to 1644 a global total order for the whole program (and this often will not be 1645 possible). The read in an atomic read-modify-write operation 1646 (<a href="#i_cmpxchg"><code>cmpxchg</code></a> and 1647 <a href="#i_atomicrmw"><code>atomicrmw</code></a>) 1648 reads the value in the modification order immediately before the value it 1649 writes. If one atomic read happens before another atomic read of the same 1650 address, the later read must see the same value or a later value in the 1651 address's modification order. This disallows reordering of 1652 <code>monotonic</code> (or stronger) operations on the same address. If an 1653 address is written <code>monotonic</code>ally by one thread, and other threads 1654 <code>monotonic</code>ally read that address repeatedly, the other threads must 1655 eventually see the write. This corresponds to the C++0x/C1x 1656 <code>memory_order_relaxed</code>.</dd> 1657 <dt><code>acquire</code></dt> 1658 <dd>In addition to the guarantees of <code>monotonic</code>, 1659 a <i>synchronizes-with</i> edge may be formed with a <code>release</code> 1660 operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd> 1661 <dt><code>release</code></dt> 1662 <dd>In addition to the guarantees of <code>monotonic</code>, if this operation 1663 writes a value which is subsequently read by an <code>acquire</code> operation, 1664 it <i>synchronizes-with</i> that operation. (This isn't a complete 1665 description; see the C++0x definition of a release sequence.) This corresponds 1666 to the C++0x/C1x <code>memory_order_release</code>.</dd> 1667 <dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an 1668 <code>acquire</code> and <code>release</code> operation on its address. 1669 This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd> 1670 <dt><code>seq_cst</code> (sequentially consistent)</dt><dd> 1671 <dd>In addition to the guarantees of <code>acq_rel</code> 1672 (<code>acquire</code> for an operation which only reads, <code>release</code> 1673 for an operation which only writes), there is a global total order on all 1674 sequentially-consistent operations on all addresses, which is consistent with 1675 the <i>happens-before</i> partial order and with the modification orders of 1676 all the affected addresses. Each sequentially-consistent read sees the last 1677 preceding write to the same address in this global order. This corresponds 1678 to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd> 1679 </dl> 1680 1681 <p id="singlethread">If an atomic operation is marked <code>singlethread</code>, 1682 it only <i>synchronizes with</i> or participates in modification and seq_cst 1683 total orderings with other operations running in the same thread (for example, 1684 in signal handlers).</p> 1685 1686 </div> 1687 1688 </div> 1689 1690 <!-- *********************************************************************** --> 1691 <h2><a name="typesystem">Type System</a></h2> 1692 <!-- *********************************************************************** --> 1693 1694 <div> 1695 1696 <p>The LLVM type system is one of the most important features of the 1697 intermediate representation. Being typed enables a number of optimizations 1698 to be performed on the intermediate representation directly, without having 1699 to do extra analyses on the side before the transformation. A strong type 1700 system makes it easier to read the generated code and enables novel analyses 1701 and transformations that are not feasible to perform on normal three address 1702 code representations.</p> 1703 1704 <!-- ======================================================================= --> 1705 <h3> 1706 <a name="t_classifications">Type Classifications</a> 1707 </h3> 1708 1709 <div> 1710 1711 <p>The types fall into a few useful classifications:</p> 1712 1713 <table border="1" cellspacing="0" cellpadding="4"> 1714 <tbody> 1715 <tr><th>Classification</th><th>Types</th></tr> 1716 <tr> 1717 <td><a href="#t_integer">integer</a></td> 1718 <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td> 1719 </tr> 1720 <tr> 1721 <td><a href="#t_floating">floating point</a></td> 1722 <td><tt>float, double, x86_fp80, fp128, ppc_fp128</tt></td> 1723 </tr> 1724 <tr> 1725 <td><a name="t_firstclass">first class</a></td> 1726 <td><a href="#t_integer">integer</a>, 1727 <a href="#t_floating">floating point</a>, 1728 <a href="#t_pointer">pointer</a>, 1729 <a href="#t_vector">vector</a>, 1730 <a href="#t_struct">structure</a>, 1731 <a href="#t_array">array</a>, 1732 <a href="#t_label">label</a>, 1733 <a href="#t_metadata">metadata</a>. 1734 </td> 1735 </tr> 1736 <tr> 1737 <td><a href="#t_primitive">primitive</a></td> 1738 <td><a href="#t_label">label</a>, 1739 <a href="#t_void">void</a>, 1740 <a href="#t_integer">integer</a>, 1741 <a href="#t_floating">floating point</a>, 1742 <a href="#t_x86mmx">x86mmx</a>, 1743 <a href="#t_metadata">metadata</a>.</td> 1744 </tr> 1745 <tr> 1746 <td><a href="#t_derived">derived</a></td> 1747 <td><a href="#t_array">array</a>, 1748 <a href="#t_function">function</a>, 1749 <a href="#t_pointer">pointer</a>, 1750 <a href="#t_struct">structure</a>, 1751 <a href="#t_vector">vector</a>, 1752 <a href="#t_opaque">opaque</a>. 1753 </td> 1754 </tr> 1755 </tbody> 1756 </table> 1757 1758 <p>The <a href="#t_firstclass">first class</a> types are perhaps the most 1759 important. Values of these types are the only ones which can be produced by 1760 instructions.</p> 1761 1762 </div> 1763 1764 <!-- ======================================================================= --> 1765 <h3> 1766 <a name="t_primitive">Primitive Types</a> 1767 </h3> 1768 1769 <div> 1770 1771 <p>The primitive types are the fundamental building blocks of the LLVM 1772 system.</p> 1773 1774 <!-- _______________________________________________________________________ --> 1775 <h4> 1776 <a name="t_integer">Integer Type</a> 1777 </h4> 1778 1779 <div> 1780 1781 <h5>Overview:</h5> 1782 <p>The integer type is a very simple type that simply specifies an arbitrary 1783 bit width for the integer type desired. Any bit width from 1 bit to 1784 2<sup>23</sup>-1 (about 8 million) can be specified.</p> 1785 1786 <h5>Syntax:</h5> 1787 <pre> 1788 iN 1789 </pre> 1790 1791 <p>The number of bits the integer will occupy is specified by the <tt>N</tt> 1792 value.</p> 1793 1794 <h5>Examples:</h5> 1795 <table class="layout"> 1796 <tr class="layout"> 1797 <td class="left"><tt>i1</tt></td> 1798 <td class="left">a single-bit integer.</td> 1799 </tr> 1800 <tr class="layout"> 1801 <td class="left"><tt>i32</tt></td> 1802 <td class="left">a 32-bit integer.</td> 1803 </tr> 1804 <tr class="layout"> 1805 <td class="left"><tt>i1942652</tt></td> 1806 <td class="left">a really big integer of over 1 million bits.</td> 1807 </tr> 1808 </table> 1809 1810 </div> 1811 1812 <!-- _______________________________________________________________________ --> 1813 <h4> 1814 <a name="t_floating">Floating Point Types</a> 1815 </h4> 1816 1817 <div> 1818 1819 <table> 1820 <tbody> 1821 <tr><th>Type</th><th>Description</th></tr> 1822 <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr> 1823 <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr> 1824 <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr> 1825 <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr> 1826 <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr> 1827 </tbody> 1828 </table> 1829 1830 </div> 1831 1832 <!-- _______________________________________________________________________ --> 1833 <h4> 1834 <a name="t_x86mmx">X86mmx Type</a> 1835 </h4> 1836 1837 <div> 1838 1839 <h5>Overview:</h5> 1840 <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> 1841 1842 <h5>Syntax:</h5> 1843 <pre> 1844 x86mmx 1845 </pre> 1846 1847 </div> 1848 1849 <!-- _______________________________________________________________________ --> 1850 <h4> 1851 <a name="t_void">Void Type</a> 1852 </h4> 1853 1854 <div> 1855 1856 <h5>Overview:</h5> 1857 <p>The void type does not represent any value and has no size.</p> 1858 1859 <h5>Syntax:</h5> 1860 <pre> 1861 void 1862 </pre> 1863 1864 </div> 1865 1866 <!-- _______________________________________________________________________ --> 1867 <h4> 1868 <a name="t_label">Label Type</a> 1869 </h4> 1870 1871 <div> 1872 1873 <h5>Overview:</h5> 1874 <p>The label type represents code labels.</p> 1875 1876 <h5>Syntax:</h5> 1877 <pre> 1878 label 1879 </pre> 1880 1881 </div> 1882 1883 <!-- _______________________________________________________________________ --> 1884 <h4> 1885 <a name="t_metadata">Metadata Type</a> 1886 </h4> 1887 1888 <div> 1889 1890 <h5>Overview:</h5> 1891 <p>The metadata type represents embedded metadata. No derived types may be 1892 created from metadata except for <a href="#t_function">function</a> 1893 arguments. 1894 1895 <h5>Syntax:</h5> 1896 <pre> 1897 metadata 1898 </pre> 1899 1900 </div> 1901 1902 </div> 1903 1904 <!-- ======================================================================= --> 1905 <h3> 1906 <a name="t_derived">Derived Types</a> 1907 </h3> 1908 1909 <div> 1910 1911 <p>The real power in LLVM comes from the derived types in the system. This is 1912 what allows a programmer to represent arrays, functions, pointers, and other 1913 useful types. Each of these types contain one or more element types which 1914 may be a primitive type, or another derived type. For example, it is 1915 possible to have a two dimensional array, using an array as the element type 1916 of another array.</p> 1917 1918 </div> 1919 1920 1921 <!-- _______________________________________________________________________ --> 1922 <h4> 1923 <a name="t_aggregate">Aggregate Types</a> 1924 </h4> 1925 1926 <div> 1927 1928 <p>Aggregate Types are a subset of derived types that can contain multiple 1929 member types. <a href="#t_array">Arrays</a>, 1930 <a href="#t_struct">structs</a>, and <a href="#t_vector">vectors</a> are 1931 aggregate types.</p> 1932 1933 </div> 1934 1935 <!-- _______________________________________________________________________ --> 1936 <h4> 1937 <a name="t_array">Array Type</a> 1938 </h4> 1939 1940 <div> 1941 1942 <h5>Overview:</h5> 1943 <p>The array type is a very simple derived type that arranges elements 1944 sequentially in memory. The array type requires a size (number of elements) 1945 and an underlying data type.</p> 1946 1947 <h5>Syntax:</h5> 1948 <pre> 1949 [<# elements> x <elementtype>] 1950 </pre> 1951 1952 <p>The number of elements is a constant integer value; <tt>elementtype</tt> may 1953 be any type with a size.</p> 1954 1955 <h5>Examples:</h5> 1956 <table class="layout"> 1957 <tr class="layout"> 1958 <td class="left"><tt>[40 x i32]</tt></td> 1959 <td class="left">Array of 40 32-bit integer values.</td> 1960 </tr> 1961 <tr class="layout"> 1962 <td class="left"><tt>[41 x i32]</tt></td> 1963 <td class="left">Array of 41 32-bit integer values.</td> 1964 </tr> 1965 <tr class="layout"> 1966 <td class="left"><tt>[4 x i8]</tt></td> 1967 <td class="left">Array of 4 8-bit integer values.</td> 1968 </tr> 1969 </table> 1970 <p>Here are some examples of multidimensional arrays:</p> 1971 <table class="layout"> 1972 <tr class="layout"> 1973 <td class="left"><tt>[3 x [4 x i32]]</tt></td> 1974 <td class="left">3x4 array of 32-bit integer values.</td> 1975 </tr> 1976 <tr class="layout"> 1977 <td class="left"><tt>[12 x [10 x float]]</tt></td> 1978 <td class="left">12x10 array of single precision floating point values.</td> 1979 </tr> 1980 <tr class="layout"> 1981 <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td> 1982 <td class="left">2x3x4 array of 16-bit integer values.</td> 1983 </tr> 1984 </table> 1985 1986 <p>There is no restriction on indexing beyond the end of the array implied by 1987 a static type (though there are restrictions on indexing beyond the bounds 1988 of an allocated object in some cases). This means that single-dimension 1989 'variable sized array' addressing can be implemented in LLVM with a zero 1990 length array type. An implementation of 'pascal style arrays' in LLVM could 1991 use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p> 1992 1993 </div> 1994 1995 <!-- _______________________________________________________________________ --> 1996 <h4> 1997 <a name="t_function">Function Type</a> 1998 </h4> 1999 2000 <div> 2001 2002 <h5>Overview:</h5> 2003 <p>The function type can be thought of as a function signature. It consists of 2004 a return type and a list of formal parameter types. The return type of a 2005 function type is a first class type or a void type.</p> 2006 2007 <h5>Syntax:</h5> 2008 <pre> 2009 <returntype> (<parameter list>) 2010 </pre> 2011 2012 <p>...where '<tt><parameter list></tt>' is a comma-separated list of type 2013 specifiers. Optionally, the parameter list may include a type <tt>...</tt>, 2014 which indicates that the function takes a variable number of arguments. 2015 Variable argument functions can access their arguments with 2016 the <a href="#int_varargs">variable argument handling intrinsic</a> 2017 functions. '<tt><returntype></tt>' is any type except 2018 <a href="#t_label">label</a>.</p> 2019 2020 <h5>Examples:</h5> 2021 <table class="layout"> 2022 <tr class="layout"> 2023 <td class="left"><tt>i32 (i32)</tt></td> 2024 <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt> 2025 </td> 2026 </tr><tr class="layout"> 2027 <td class="left"><tt>float (i16, i32 *) * 2028 </tt></td> 2029 <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes 2030 an <tt>i16</tt> and a <a href="#t_pointer">pointer</a> to <tt>i32</tt>, 2031 returning <tt>float</tt>. 2032 </td> 2033 </tr><tr class="layout"> 2034 <td class="left"><tt>i32 (i8*, ...)</tt></td> 2035 <td class="left">A vararg function that takes at least one 2036 <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C), 2037 which returns an integer. This is the signature for <tt>printf</tt> in 2038 LLVM. 2039 </td> 2040 </tr><tr class="layout"> 2041 <td class="left"><tt>{i32, i32} (i32)</tt></td> 2042 <td class="left">A function taking an <tt>i32</tt>, returning a 2043 <a href="#t_struct">structure</a> containing two <tt>i32</tt> values 2044 </td> 2045 </tr> 2046 </table> 2047 2048 </div> 2049 2050 <!-- _______________________________________________________________________ --> 2051 <h4> 2052 <a name="t_struct">Structure Type</a> 2053 </h4> 2054 2055 <div> 2056 2057 <h5>Overview:</h5> 2058 <p>The structure type is used to represent a collection of data members together 2059 in memory. The elements of a structure may be any type that has a size.</p> 2060 2061 <p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>' 2062 and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field 2063 with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction. 2064 Structures in registers are accessed using the 2065 '<tt><a href="#i_extractvalue">extractvalue</a></tt>' and 2066 '<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p> 2067 2068 <p>Structures may optionally be "packed" structures, which indicate that the 2069 alignment of the struct is one byte, and that there is no padding between 2070 the elements. In non-packed structs, padding between field types is inserted 2071 as defined by the TargetData string in the module, which is required to match 2072 what the underlying code generator expects.</p> 2073 2074 <p>Structures can either be "literal" or "identified". A literal structure is 2075 defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified 2076 types are always defined at the top level with a name. Literal types are 2077 uniqued by their contents and can never be recursive or opaque since there is 2078 no way to write one. Identified types can be recursive, can be opaqued, and are 2079 never uniqued. 2080 </p> 2081 2082 <h5>Syntax:</h5> 2083 <pre> 2084 %T1 = type { <type list> } <i>; Identified normal struct type</i> 2085 %T2 = type <{ <type list> }> <i>; Identified packed struct type</i> 2086 </pre> 2087 2088 <h5>Examples:</h5> 2089 <table class="layout"> 2090 <tr class="layout"> 2091 <td class="left"><tt>{ i32, i32, i32 }</tt></td> 2092 <td class="left">A triple of three <tt>i32</tt> values</td> 2093 </tr> 2094 <tr class="layout"> 2095 <td class="left"><tt>{ float, i32 (i32) * }</tt></td> 2096 <td class="left">A pair, where the first element is a <tt>float</tt> and the 2097 second element is a <a href="#t_pointer">pointer</a> to a 2098 <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning 2099 an <tt>i32</tt>.</td> 2100 </tr> 2101 <tr class="layout"> 2102 <td class="left"><tt><{ i8, i32 }></tt></td> 2103 <td class="left">A packed struct known to be 5 bytes in size.</td> 2104 </tr> 2105 </table> 2106 2107 </div> 2108 2109 <!-- _______________________________________________________________________ --> 2110 <h4> 2111 <a name="t_opaque">Opaque Structure Types</a> 2112 </h4> 2113 2114 <div> 2115 2116 <h5>Overview:</h5> 2117 <p>Opaque structure types are used to represent named structure types that do 2118 not have a body specified. This corresponds (for example) to the C notion of 2119 a forward declared structure.</p> 2120 2121 <h5>Syntax:</h5> 2122 <pre> 2123 %X = type opaque 2124 %52 = type opaque 2125 </pre> 2126 2127 <h5>Examples:</h5> 2128 <table class="layout"> 2129 <tr class="layout"> 2130 <td class="left"><tt>opaque</tt></td> 2131 <td class="left">An opaque type.</td> 2132 </tr> 2133 </table> 2134 2135 </div> 2136 2137 2138 2139 <!-- _______________________________________________________________________ --> 2140 <h4> 2141 <a name="t_pointer">Pointer Type</a> 2142 </h4> 2143 2144 <div> 2145 2146 <h5>Overview:</h5> 2147 <p>The pointer type is used to specify memory locations. 2148 Pointers are commonly used to reference objects in memory.</p> 2149 2150 <p>Pointer types may have an optional address space attribute defining the 2151 numbered address space where the pointed-to object resides. The default 2152 address space is number zero. The semantics of non-zero address 2153 spaces are target-specific.</p> 2154 2155 <p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it 2156 permit pointers to labels (<tt>label*</tt>). Use <tt>i8*</tt> instead.</p> 2157 2158 <h5>Syntax:</h5> 2159 <pre> 2160 <type> * 2161 </pre> 2162 2163 <h5>Examples:</h5> 2164 <table class="layout"> 2165 <tr class="layout"> 2166 <td class="left"><tt>[4 x i32]*</tt></td> 2167 <td class="left">A <a href="#t_pointer">pointer</a> to <a 2168 href="#t_array">array</a> of four <tt>i32</tt> values.</td> 2169 </tr> 2170 <tr class="layout"> 2171 <td class="left"><tt>i32 (i32*) *</tt></td> 2172 <td class="left"> A <a href="#t_pointer">pointer</a> to a <a 2173 href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an 2174 <tt>i32</tt>.</td> 2175 </tr> 2176 <tr class="layout"> 2177 <td class="left"><tt>i32 addrspace(5)*</tt></td> 2178 <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value 2179 that resides in address space #5.</td> 2180 </tr> 2181 </table> 2182 2183 </div> 2184 2185 <!-- _______________________________________________________________________ --> 2186 <h4> 2187 <a name="t_vector">Vector Type</a> 2188 </h4> 2189 2190 <div> 2191 2192 <h5>Overview:</h5> 2193 <p>A vector type is a simple derived type that represents a vector of elements. 2194 Vector types are used when multiple primitive data are operated in parallel 2195 using a single instruction (SIMD). A vector type requires a size (number of 2196 elements) and an underlying primitive data type. Vector types are considered 2197 <a href="#t_firstclass">first class</a>.</p> 2198 2199 <h5>Syntax:</h5> 2200 <pre> 2201 < <# elements> x <elementtype> > 2202 </pre> 2203 2204 <p>The number of elements is a constant integer value larger than 0; elementtype 2205 may be any integer or floating point type. Vectors of size zero are not 2206 allowed, and pointers are not allowed as the element type.</p> 2207 2208 <h5>Examples:</h5> 2209 <table class="layout"> 2210 <tr class="layout"> 2211 <td class="left"><tt><4 x i32></tt></td> 2212 <td class="left">Vector of 4 32-bit integer values.</td> 2213 </tr> 2214 <tr class="layout"> 2215 <td class="left"><tt><8 x float></tt></td> 2216 <td class="left">Vector of 8 32-bit floating-point values.</td> 2217 </tr> 2218 <tr class="layout"> 2219 <td class="left"><tt><2 x i64></tt></td> 2220 <td class="left">Vector of 2 64-bit integer values.</td> 2221 </tr> 2222 </table> 2223 2224 </div> 2225 2226 </div> 2227 2228 <!-- *********************************************************************** --> 2229 <h2><a name="constants">Constants</a></h2> 2230 <!-- *********************************************************************** --> 2231 2232 <div> 2233 2234 <p>LLVM has several different basic types of constants. This section describes 2235 them all and their syntax.</p> 2236 2237 <!-- ======================================================================= --> 2238 <h3> 2239 <a name="simpleconstants">Simple Constants</a> 2240 </h3> 2241 2242 <div> 2243 2244 <dl> 2245 <dt><b>Boolean constants</b></dt> 2246 <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid 2247 constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd> 2248 2249 <dt><b>Integer constants</b></dt> 2250 <dd>Standard integers (such as '4') are constants of 2251 the <a href="#t_integer">integer</a> type. Negative numbers may be used 2252 with integer types.</dd> 2253 2254 <dt><b>Floating point constants</b></dt> 2255 <dd>Floating point constants use standard decimal notation (e.g. 123.421), 2256 exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal 2257 notation (see below). The assembler requires the exact decimal value of a 2258 floating-point constant. For example, the assembler accepts 1.25 but 2259 rejects 1.3 because 1.3 is a repeating decimal in binary. Floating point 2260 constants must have a <a href="#t_floating">floating point</a> type. </dd> 2261 2262 <dt><b>Null pointer constants</b></dt> 2263 <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant 2264 and must be of <a href="#t_pointer">pointer type</a>.</dd> 2265 </dl> 2266 2267 <p>The one non-intuitive notation for constants is the hexadecimal form of 2268 floating point constants. For example, the form '<tt>double 2269 0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) 2270 '<tt>double 4.5e+15</tt>'. The only time hexadecimal floating point 2271 constants are required (and the only time that they are generated by the 2272 disassembler) is when a floating point constant must be emitted but it cannot 2273 be represented as a decimal floating point number in a reasonable number of 2274 digits. For example, NaN's, infinities, and other special values are 2275 represented in their IEEE hexadecimal format so that assembly and disassembly 2276 do not cause any bits to change in the constants.</p> 2277 2278 <p>When using the hexadecimal form, constants of types float and double are 2279 represented using the 16-digit form shown above (which matches the IEEE754 2280 representation for double); float values must, however, be exactly 2281 representable as IEE754 single precision. Hexadecimal format is always used 2282 for long double, and there are three forms of long double. The 80-bit format 2283 used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits. 2284 The 128-bit format used by PowerPC (two adjacent doubles) is represented 2285 by <tt>0xM</tt> followed by 32 hexadecimal digits. The IEEE 128-bit format 2286 is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no 2287 currently supported target uses this format. Long doubles will only work if 2288 they match the long double format on your target. All hexadecimal formats 2289 are big-endian (sign bit at the left).</p> 2290 2291 <p>There are no constants of type x86mmx.</p> 2292 </div> 2293 2294 <!-- ======================================================================= --> 2295 <h3> 2296 <a name="aggregateconstants"></a> <!-- old anchor --> 2297 <a name="complexconstants">Complex Constants</a> 2298 </h3> 2299 2300 <div> 2301 2302 <p>Complex constants are a (potentially recursive) combination of simple 2303 constants and smaller complex constants.</p> 2304 2305 <dl> 2306 <dt><b>Structure constants</b></dt> 2307 <dd>Structure constants are represented with notation similar to structure 2308 type definitions (a comma separated list of elements, surrounded by braces 2309 (<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>", 2310 where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>". 2311 Structure constants must have <a href="#t_struct">structure type</a>, and 2312 the number and types of elements must match those specified by the 2313 type.</dd> 2314 2315 <dt><b>Array constants</b></dt> 2316 <dd>Array constants are represented with notation similar to array type 2317 definitions (a comma separated list of elements, surrounded by square 2318 brackets (<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 2319 ]</tt>". Array constants must have <a href="#t_array">array type</a>, and 2320 the number and types of elements must match those specified by the 2321 type.</dd> 2322 2323 <dt><b>Vector constants</b></dt> 2324 <dd>Vector constants are represented with notation similar to vector type 2325 definitions (a comma separated list of elements, surrounded by 2326 less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 2327 42, i32 11, i32 74, i32 100 ></tt>". Vector constants must 2328 have <a href="#t_vector">vector type</a>, and the number and types of 2329 elements must match those specified by the type.</dd> 2330 2331 <dt><b>Zero initialization</b></dt> 2332 <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a 2333 value to zero of <em>any</em> type, including scalar and 2334 <a href="#t_aggregate">aggregate</a> types. 2335 This is often used to avoid having to print large zero initializers 2336 (e.g. for large arrays) and is always exactly equivalent to using explicit 2337 zero initializers.</dd> 2338 2339 <dt><b>Metadata node</b></dt> 2340 <dd>A metadata node is a structure-like constant with 2341 <a href="#t_metadata">metadata type</a>. For example: "<tt>metadata !{ 2342 i32 0, metadata !"test" }</tt>". Unlike other constants that are meant to 2343 be interpreted as part of the instruction stream, metadata is a place to 2344 attach additional information such as debug info.</dd> 2345 </dl> 2346 2347 </div> 2348 2349 <!-- ======================================================================= --> 2350 <h3> 2351 <a name="globalconstants">Global Variable and Function Addresses</a> 2352 </h3> 2353 2354 <div> 2355 2356 <p>The addresses of <a href="#globalvars">global variables</a> 2357 and <a href="#functionstructure">functions</a> are always implicitly valid 2358 (link-time) constants. These constants are explicitly referenced when 2359 the <a href="#identifiers">identifier for the global</a> is used and always 2360 have <a href="#t_pointer">pointer</a> type. For example, the following is a 2361 legal LLVM file:</p> 2362 2363 <pre class="doc_code"> 2364 @X = global i32 17 2365 @Y = global i32 42 2366 @Z = global [2 x i32*] [ i32* @X, i32* @Y ] 2367 </pre> 2368 2369 </div> 2370 2371 <!-- ======================================================================= --> 2372 <h3> 2373 <a name="undefvalues">Undefined Values</a> 2374 </h3> 2375 2376 <div> 2377 2378 <p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and 2379 indicates that the user of the value may receive an unspecified bit-pattern. 2380 Undefined values may be of any type (other than '<tt>label</tt>' 2381 or '<tt>void</tt>') and be used anywhere a constant is permitted.</p> 2382 2383 <p>Undefined values are useful because they indicate to the compiler that the 2384 program is well defined no matter what value is used. This gives the 2385 compiler more freedom to optimize. Here are some examples of (potentially 2386 surprising) transformations that are valid (in pseudo IR):</p> 2387 2388 2389 <pre class="doc_code"> 2390 %A = add %X, undef 2391 %B = sub %X, undef 2392 %C = xor %X, undef 2393 Safe: 2394 %A = undef 2395 %B = undef 2396 %C = undef 2397 </pre> 2398 2399 <p>This is safe because all of the output bits are affected by the undef bits. 2400 Any output bit can have a zero or one depending on the input bits.</p> 2401 2402 <pre class="doc_code"> 2403 %A = or %X, undef 2404 %B = and %X, undef 2405 Safe: 2406 %A = -1 2407 %B = 0 2408 Unsafe: 2409 %A = undef 2410 %B = undef 2411 </pre> 2412 2413 <p>These logical operations have bits that are not always affected by the input. 2414 For example, if <tt>%X</tt> has a zero bit, then the output of the 2415 '<tt>and</tt>' operation will always be a zero for that bit, no matter what 2416 the corresponding bit from the '<tt>undef</tt>' is. As such, it is unsafe to 2417 optimize or assume that the result of the '<tt>and</tt>' is '<tt>undef</tt>'. 2418 However, it is safe to assume that all bits of the '<tt>undef</tt>' could be 2419 0, and optimize the '<tt>and</tt>' to 0. Likewise, it is safe to assume that 2420 all the bits of the '<tt>undef</tt>' operand to the '<tt>or</tt>' could be 2421 set, allowing the '<tt>or</tt>' to be folded to -1.</p> 2422 2423 <pre class="doc_code"> 2424 %A = select undef, %X, %Y 2425 %B = select undef, 42, %Y 2426 %C = select %X, %Y, undef 2427 Safe: 2428 %A = %X (or %Y) 2429 %B = 42 (or %Y) 2430 %C = %Y 2431 Unsafe: 2432 %A = undef 2433 %B = undef 2434 %C = undef 2435 </pre> 2436 2437 <p>This set of examples shows that undefined '<tt>select</tt>' (and conditional 2438 branch) conditions can go <em>either way</em>, but they have to come from one 2439 of the two operands. In the <tt>%A</tt> example, if <tt>%X</tt> and 2440 <tt>%Y</tt> were both known to have a clear low bit, then <tt>%A</tt> would 2441 have to have a cleared low bit. However, in the <tt>%C</tt> example, the 2442 optimizer is allowed to assume that the '<tt>undef</tt>' operand could be the 2443 same as <tt>%Y</tt>, allowing the whole '<tt>select</tt>' to be 2444 eliminated.</p> 2445 2446 <pre class="doc_code"> 2447 %A = xor undef, undef 2448 2449 %B = undef 2450 %C = xor %B, %B 2451 2452 %D = undef 2453 %E = icmp lt %D, 4 2454 %F = icmp gte %D, 4 2455 2456 Safe: 2457 %A = undef 2458 %B = undef 2459 %C = undef 2460 %D = undef 2461 %E = undef 2462 %F = undef 2463 </pre> 2464 2465 <p>This example points out that two '<tt>undef</tt>' operands are not 2466 necessarily the same. This can be surprising to people (and also matches C 2467 semantics) where they assume that "<tt>X^X</tt>" is always zero, even 2468 if <tt>X</tt> is undefined. This isn't true for a number of reasons, but the 2469 short answer is that an '<tt>undef</tt>' "variable" can arbitrarily change 2470 its value over its "live range". This is true because the variable doesn't 2471 actually <em>have a live range</em>. Instead, the value is logically read 2472 from arbitrary registers that happen to be around when needed, so the value 2473 is not necessarily consistent over time. In fact, <tt>%A</tt> and <tt>%C</tt> 2474 need to have the same semantics or the core LLVM "replace all uses with" 2475 concept would not hold.</p> 2476 2477 <pre class="doc_code"> 2478 %A = fdiv undef, %X 2479 %B = fdiv %X, undef 2480 Safe: 2481 %A = undef 2482 b: unreachable 2483 </pre> 2484 2485 <p>These examples show the crucial difference between an <em>undefined 2486 value</em> and <em>undefined behavior</em>. An undefined value (like 2487 '<tt>undef</tt>') is allowed to have an arbitrary bit-pattern. This means that 2488 the <tt>%A</tt> operation can be constant folded to '<tt>undef</tt>', because 2489 the '<tt>undef</tt>' could be an SNaN, and <tt>fdiv</tt> is not (currently) 2490 defined on SNaN's. However, in the second example, we can make a more 2491 aggressive assumption: because the <tt>undef</tt> is allowed to be an 2492 arbitrary value, we are allowed to assume that it could be zero. Since a 2493 divide by zero has <em>undefined behavior</em>, we are allowed to assume that 2494 the operation does not execute at all. This allows us to delete the divide and 2495 all code after it. Because the undefined operation "can't happen", the 2496 optimizer can assume that it occurs in dead code.</p> 2497 2498 <pre class="doc_code"> 2499 a: store undef -> %X 2500 b: store %X -> undef 2501 Safe: 2502 a: <deleted> 2503 b: unreachable 2504 </pre> 2505 2506 <p>These examples reiterate the <tt>fdiv</tt> example: a store <em>of</em> an 2507 undefined value can be assumed to not have any effect; we can assume that the 2508 value is overwritten with bits that happen to match what was already there. 2509 However, a store <em>to</em> an undefined location could clobber arbitrary 2510 memory, therefore, it has undefined behavior.</p> 2511 2512 </div> 2513 2514 <!-- ======================================================================= --> 2515 <h3> 2516 <a name="trapvalues">Trap Values</a> 2517 </h3> 2518 2519 <div> 2520 2521 <p>Trap values are similar to <a href="#undefvalues">undef values</a>, however 2522 instead of representing an unspecified bit pattern, they represent the 2523 fact that an instruction or constant expression which cannot evoke side 2524 effects has nevertheless detected a condition which results in undefined 2525 behavior.</p> 2526 2527 <p>There is currently no way of representing a trap value in the IR; they 2528 only exist when produced by operations such as 2529 <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p> 2530 2531 <p>Trap value behavior is defined in terms of value <i>dependence</i>:</p> 2532 2533 <ul> 2534 <li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on 2535 their operands.</li> 2536 2537 <li><a href="#i_phi"><tt>Phi</tt></a> nodes depend on the operand corresponding 2538 to their dynamic predecessor basic block.</li> 2539 2540 <li>Function arguments depend on the corresponding actual argument values in 2541 the dynamic callers of their functions.</li> 2542 2543 <li><a href="#i_call"><tt>Call</tt></a> instructions depend on the 2544 <a href="#i_ret"><tt>ret</tt></a> instructions that dynamically transfer 2545 control back to them.</li> 2546 2547 <li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the 2548 <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_unwind"><tt>unwind</tt></a>, 2549 or exception-throwing call instructions that dynamically transfer control 2550 back to them.</li> 2551 2552 <li>Non-volatile loads and stores depend on the most recent stores to all of the 2553 referenced memory addresses, following the order in the IR 2554 (including loads and stores implied by intrinsics such as 2555 <a href="#int_memcpy"><tt>@llvm.memcpy</tt></a>.)</li> 2556 2557 <!-- TODO: In the case of multiple threads, this only applies if the store 2558 "happens-before" the load or store. --> 2559 2560 <!-- TODO: floating-point exception state --> 2561 2562 <li>An instruction with externally visible side effects depends on the most 2563 recent preceding instruction with externally visible side effects, following 2564 the order in the IR. (This includes 2565 <a href="#volatile">volatile operations</a>.)</li> 2566 2567 <li>An instruction <i>control-depends</i> on a 2568 <a href="#terminators">terminator instruction</a> 2569 if the terminator instruction has multiple successors and the instruction 2570 is always executed when control transfers to one of the successors, and 2571 may not be executed when control is transferred to another.</li> 2572 2573 <li>Additionally, an instruction also <i>control-depends</i> on a terminator 2574 instruction if the set of instructions it otherwise depends on would be 2575 different if the terminator had transferred control to a different 2576 successor.</li> 2577 2578 <li>Dependence is transitive.</li> 2579 2580 </ul> 2581 2582 <p>Whenever a trap value is generated, all values which depend on it evaluate 2583 to trap. If they have side effects, they evoke their side effects as if each 2584 operand with a trap value were undef. If they have externally-visible side 2585 effects, the behavior is undefined.</p> 2586 2587 <p>Here are some examples:</p> 2588 2589 <pre class="doc_code"> 2590 entry: 2591 %trap = sub nuw i32 0, 1 ; Results in a trap value. 2592 %still_trap = and i32 %trap, 0 ; Whereas (and i32 undef, 0) would return 0. 2593 %trap_yet_again = getelementptr i32* @h, i32 %still_trap 2594 store i32 0, i32* %trap_yet_again ; undefined behavior 2595 2596 store i32 %trap, i32* @g ; Trap value conceptually stored to memory. 2597 %trap2 = load i32* @g ; Returns a trap value, not just undef. 2598 2599 volatile store i32 %trap, i32* @g ; External observation; undefined behavior. 2600 2601 %narrowaddr = bitcast i32* @g to i16* 2602 %wideaddr = bitcast i32* @g to i64* 2603 %trap3 = load i16* %narrowaddr ; Returns a trap value. 2604 %trap4 = load i64* %wideaddr ; Returns a trap value. 2605 2606 %cmp = icmp slt i32 %trap, 0 ; Returns a trap value. 2607 br i1 %cmp, label %true, label %end ; Branch to either destination. 2608 2609 true: 2610 volatile store i32 0, i32* @g ; This is control-dependent on %cmp, so 2611 ; it has undefined behavior. 2612 br label %end 2613 2614 end: 2615 %p = phi i32 [ 0, %entry ], [ 1, %true ] 2616 ; Both edges into this PHI are 2617 ; control-dependent on %cmp, so this 2618 ; always results in a trap value. 2619 2620 volatile store i32 0, i32* @g ; This would depend on the store in %true 2621 ; if %cmp is true, or the store in %entry 2622 ; otherwise, so this is undefined behavior. 2623 2624 br i1 %cmp, label %second_true, label %second_end 2625 ; The same branch again, but this time the 2626 ; true block doesn't have side effects. 2627 2628 second_true: 2629 ; No side effects! 2630 ret void 2631 2632 second_end: 2633 volatile store i32 0, i32* @g ; This time, the instruction always depends 2634 ; on the store in %end. Also, it is 2635 ; control-equivalent to %end, so this is 2636 ; well-defined (again, ignoring earlier 2637 ; undefined behavior in this example). 2638 </pre> 2639 2640 </div> 2641 2642 <!-- ======================================================================= --> 2643 <h3> 2644 <a name="blockaddress">Addresses of Basic Blocks</a> 2645 </h3> 2646 2647 <div> 2648 2649 <p><b><tt>blockaddress(@function, %block)</tt></b></p> 2650 2651 <p>The '<tt>blockaddress</tt>' constant computes the address of the specified 2652 basic block in the specified function, and always has an i8* type. Taking 2653 the address of the entry block is illegal.</p> 2654 2655 <p>This value only has defined behavior when used as an operand to the 2656 '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction, or for 2657 comparisons against null. Pointer equality tests between labels addresses 2658 results in undefined behavior — though, again, comparison against null 2659 is ok, and no label is equal to the null pointer. This may be passed around 2660 as an opaque pointer sized value as long as the bits are not inspected. This 2661 allows <tt>ptrtoint</tt> and arithmetic to be performed on these values so 2662 long as the original value is reconstituted before the <tt>indirectbr</tt> 2663 instruction.</p> 2664 2665 <p>Finally, some targets may provide defined semantics when using the value as 2666 the operand to an inline assembly, but that is target specific.</p> 2667 2668 </div> 2669 2670 2671 <!-- ======================================================================= --> 2672 <h3> 2673 <a name="constantexprs">Constant Expressions</a> 2674 </h3> 2675 2676 <div> 2677 2678 <p>Constant expressions are used to allow expressions involving other constants 2679 to be used as constants. Constant expressions may be of 2680 any <a href="#t_firstclass">first class</a> type and may involve any LLVM 2681 operation that does not have side effects (e.g. load and call are not 2682 supported). The following is the syntax for constant expressions:</p> 2683 2684 <dl> 2685 <dt><b><tt>trunc (CST to TYPE)</tt></b></dt> 2686 <dd>Truncate a constant to another type. The bit size of CST must be larger 2687 than the bit size of TYPE. Both types must be integers.</dd> 2688 2689 <dt><b><tt>zext (CST to TYPE)</tt></b></dt> 2690 <dd>Zero extend a constant to another type. The bit size of CST must be 2691 smaller than the bit size of TYPE. Both types must be integers.</dd> 2692 2693 <dt><b><tt>sext (CST to TYPE)</tt></b></dt> 2694 <dd>Sign extend a constant to another type. The bit size of CST must be 2695 smaller than the bit size of TYPE. Both types must be integers.</dd> 2696 2697 <dt><b><tt>fptrunc (CST to TYPE)</tt></b></dt> 2698 <dd>Truncate a floating point constant to another floating point type. The 2699 size of CST must be larger than the size of TYPE. Both types must be 2700 floating point.</dd> 2701 2702 <dt><b><tt>fpext (CST to TYPE)</tt></b></dt> 2703 <dd>Floating point extend a constant to another type. The size of CST must be 2704 smaller or equal to the size of TYPE. Both types must be floating 2705 point.</dd> 2706 2707 <dt><b><tt>fptoui (CST to TYPE)</tt></b></dt> 2708 <dd>Convert a floating point constant to the corresponding unsigned integer 2709 constant. TYPE must be a scalar or vector integer type. CST must be of 2710 scalar or vector floating point type. Both CST and TYPE must be scalars, 2711 or vectors of the same number of elements. If the value won't fit in the 2712 integer type, the results are undefined.</dd> 2713 2714 <dt><b><tt>fptosi (CST to TYPE)</tt></b></dt> 2715 <dd>Convert a floating point constant to the corresponding signed integer 2716 constant. TYPE must be a scalar or vector integer type. CST must be of 2717 scalar or vector floating point type. Both CST and TYPE must be scalars, 2718 or vectors of the same number of elements. If the value won't fit in the 2719 integer type, the results are undefined.</dd> 2720 2721 <dt><b><tt>uitofp (CST to TYPE)</tt></b></dt> 2722 <dd>Convert an unsigned integer constant to the corresponding floating point 2723 constant. TYPE must be a scalar or vector floating point type. CST must be 2724 of scalar or vector integer type. Both CST and TYPE must be scalars, or 2725 vectors of the same number of elements. If the value won't fit in the 2726 floating point type, the results are undefined.</dd> 2727 2728 <dt><b><tt>sitofp (CST to TYPE)</tt></b></dt> 2729 <dd>Convert a signed integer constant to the corresponding floating point 2730 constant. TYPE must be a scalar or vector floating point type. CST must be 2731 of scalar or vector integer type. Both CST and TYPE must be scalars, or 2732 vectors of the same number of elements. If the value won't fit in the 2733 floating point type, the results are undefined.</dd> 2734 2735 <dt><b><tt>ptrtoint (CST to TYPE)</tt></b></dt> 2736 <dd>Convert a pointer typed constant to the corresponding integer constant 2737 <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer 2738 type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to 2739 make it fit in <tt>TYPE</tt>.</dd> 2740 2741 <dt><b><tt>inttoptr (CST to TYPE)</tt></b></dt> 2742 <dd>Convert a integer constant to a pointer constant. TYPE must be a pointer 2743 type. CST must be of integer type. The CST value is zero extended, 2744 truncated, or unchanged to make it fit in a pointer size. This one is 2745 <i>really</i> dangerous!</dd> 2746 2747 <dt><b><tt>bitcast (CST to TYPE)</tt></b></dt> 2748 <dd>Convert a constant, CST, to another TYPE. The constraints of the operands 2749 are the same as those for the <a href="#i_bitcast">bitcast 2750 instruction</a>.</dd> 2751 2752 <dt><b><tt>getelementptr (CSTPTR, IDX0, IDX1, ...)</tt></b></dt> 2753 <dt><b><tt>getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)</tt></b></dt> 2754 <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on 2755 constants. As with the <a href="#i_getelementptr">getelementptr</a> 2756 instruction, the index list may have zero or more indexes, which are 2757 required to make sense for the type of "CSTPTR".</dd> 2758 2759 <dt><b><tt>select (COND, VAL1, VAL2)</tt></b></dt> 2760 <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd> 2761 2762 <dt><b><tt>icmp COND (VAL1, VAL2)</tt></b></dt> 2763 <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd> 2764 2765 <dt><b><tt>fcmp COND (VAL1, VAL2)</tt></b></dt> 2766 <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd> 2767 2768 <dt><b><tt>extractelement (VAL, IDX)</tt></b></dt> 2769 <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on 2770 constants.</dd> 2771 2772 <dt><b><tt>insertelement (VAL, ELT, IDX)</tt></b></dt> 2773 <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on 2774 constants.</dd> 2775 2776 <dt><b><tt>shufflevector (VEC1, VEC2, IDXMASK)</tt></b></dt> 2777 <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on 2778 constants.</dd> 2779 2780 <dt><b><tt>extractvalue (VAL, IDX0, IDX1, ...)</tt></b></dt> 2781 <dd>Perform the <a href="#i_extractvalue">extractvalue operation</a> on 2782 constants. The index list is interpreted in a similar manner as indices in 2783 a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one 2784 index value must be specified.</dd> 2785 2786 <dt><b><tt>insertvalue (VAL, ELT, IDX0, IDX1, ...)</tt></b></dt> 2787 <dd>Perform the <a href="#i_insertvalue">insertvalue operation</a> on 2788 constants. The index list is interpreted in a similar manner as indices in 2789 a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one 2790 index value must be specified.</dd> 2791 2792 <dt><b><tt>OPCODE (LHS, RHS)</tt></b></dt> 2793 <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may 2794 be any of the <a href="#binaryops">binary</a> 2795 or <a href="#bitwiseops">bitwise binary</a> operations. The constraints 2796 on operands are the same as those for the corresponding instruction 2797 (e.g. no bitwise operations on floating point values are allowed).</dd> 2798 </dl> 2799 2800 </div> 2801 2802 </div> 2803 2804 <!-- *********************************************************************** --> 2805 <h2><a name="othervalues">Other Values</a></h2> 2806 <!-- *********************************************************************** --> 2807 <div> 2808 <!-- ======================================================================= --> 2809 <h3> 2810 <a name="inlineasm">Inline Assembler Expressions</a> 2811 </h3> 2812 2813 <div> 2814 2815 <p>LLVM supports inline assembler expressions (as opposed 2816 to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of 2817 a special value. This value represents the inline assembler as a string 2818 (containing the instructions to emit), a list of operand constraints (stored 2819 as a string), a flag that indicates whether or not the inline asm 2820 expression has side effects, and a flag indicating whether the function 2821 containing the asm needs to align its stack conservatively. An example 2822 inline assembler expression is:</p> 2823 2824 <pre class="doc_code"> 2825 i32 (i32) asm "bswap $0", "=r,r" 2826 </pre> 2827 2828 <p>Inline assembler expressions may <b>only</b> be used as the callee operand of 2829 a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we 2830 have:</p> 2831 2832 <pre class="doc_code"> 2833 %X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y) 2834 </pre> 2835 2836 <p>Inline asms with side effects not visible in the constraint list must be 2837 marked as having side effects. This is done through the use of the 2838 '<tt>sideeffect</tt>' keyword, like so:</p> 2839 2840 <pre class="doc_code"> 2841 call void asm sideeffect "eieio", ""() 2842 </pre> 2843 2844 <p>In some cases inline asms will contain code that will not work unless the 2845 stack is aligned in some way, such as calls or SSE instructions on x86, 2846 yet will not contain code that does that alignment within the asm. 2847 The compiler should make conservative assumptions about what the asm might 2848 contain and should generate its usual stack alignment code in the prologue 2849 if the '<tt>alignstack</tt>' keyword is present:</p> 2850 2851 <pre class="doc_code"> 2852 call void asm alignstack "eieio", ""() 2853 </pre> 2854 2855 <p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come 2856 first.</p> 2857 2858 <p>TODO: The format of the asm and constraints string still need to be 2859 documented here. Constraints on what can be done (e.g. duplication, moving, 2860 etc need to be documented). This is probably best done by reference to 2861 another document that covers inline asm from a holistic perspective.</p> 2862 2863 <h4> 2864 <a name="inlineasm_md">Inline Asm Metadata</a> 2865 </h4> 2866 2867 <div> 2868 2869 <p>The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode 2870 attached to it that contains a list of constant integers. If present, the 2871 code generator will use the integer as the location cookie value when report 2872 errors through the LLVMContext error reporting mechanisms. This allows a 2873 front-end to correlate backend errors that occur with inline asm back to the 2874 source code that produced it. For example:</p> 2875 2876 <pre class="doc_code"> 2877 call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b> 2878 ... 2879 !42 = !{ i32 1234567 } 2880 </pre> 2881 2882 <p>It is up to the front-end to make sense of the magic numbers it places in the 2883 IR. If the MDNode contains multiple constants, the code generator will use 2884 the one that corresponds to the line of the asm that the error occurs on.</p> 2885 2886 </div> 2887 2888 </div> 2889 2890 <!-- ======================================================================= --> 2891 <h3> 2892 <a name="metadata">Metadata Nodes and Metadata Strings</a> 2893 </h3> 2894 2895 <div> 2896 2897 <p>LLVM IR allows metadata to be attached to instructions in the program that 2898 can convey extra information about the code to the optimizers and code 2899 generator. One example application of metadata is source-level debug 2900 information. There are two metadata primitives: strings and nodes. All 2901 metadata has the <tt>metadata</tt> type and is identified in syntax by a 2902 preceding exclamation point ('<tt>!</tt>').</p> 2903 2904 <p>A metadata string is a string surrounded by double quotes. It can contain 2905 any character by escaping non-printable characters with "\xx" where "xx" is 2906 the two digit hex code. For example: "<tt>!"test\00"</tt>".</p> 2907 2908 <p>Metadata nodes are represented with notation similar to structure constants 2909 (a comma separated list of elements, surrounded by braces and preceded by an 2910 exclamation point). For example: "<tt>!{ metadata !"test\00", i32 2911 10}</tt>". Metadata nodes can have any values as their operand.</p> 2912 2913 <p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of 2914 metadata nodes, which can be looked up in the module symbol table. For 2915 example: "<tt>!foo = metadata !{!4, !3}</tt>". 2916 2917 <p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt> 2918 function is using two metadata arguments.</p> 2919 2920 <div class="doc_code"> 2921 <pre> 2922 call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) 2923 </pre> 2924 </div> 2925 2926 <p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is 2927 attached with <tt>add</tt> instruction using <tt>!dbg</tt> identifier.</p> 2928 2929 <div class="doc_code"> 2930 <pre> 2931 %indvar.next = add i64 %indvar, 1, !dbg !21 2932 </pre> 2933 </div> 2934 2935 </div> 2936 2937 </div> 2938 2939 <!-- *********************************************************************** --> 2940 <h2> 2941 <a name="intrinsic_globals">Intrinsic Global Variables</a> 2942 </h2> 2943 <!-- *********************************************************************** --> 2944 <div> 2945 <p>LLVM has a number of "magic" global variables that contain data that affect 2946 code generation or other IR semantics. These are documented here. All globals 2947 of this sort should have a section specified as "<tt>llvm.metadata</tt>". This 2948 section and all globals that start with "<tt>llvm.</tt>" are reserved for use 2949 by LLVM.</p> 2950 2951 <!-- ======================================================================= --> 2952 <h3> 2953 <a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a> 2954 </h3> 2955 2956 <div> 2957 2958 <p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a 2959 href="#linkage_appending">appending linkage</a>. This array contains a list of 2960 pointers to global variables and functions which may optionally have a pointer 2961 cast formed of bitcast or getelementptr. For example, a legal use of it is:</p> 2962 2963 <pre> 2964 @X = global i8 4 2965 @Y = global i32 123 2966 2967 @llvm.used = appending global [2 x i8*] [ 2968 i8* @X, 2969 i8* bitcast (i32* @Y to i8*) 2970 ], section "llvm.metadata" 2971 </pre> 2972 2973 <p>If a global variable appears in the <tt>@llvm.used</tt> list, then the 2974 compiler, assembler, and linker are required to treat the symbol as if there is 2975 a reference to the global that it cannot see. For example, if a variable has 2976 internal linkage and no references other than that from the <tt>@llvm.used</tt> 2977 list, it cannot be deleted. This is commonly used to represent references from 2978 inline asms and other things the compiler cannot "see", and corresponds to 2979 "attribute((used))" in GNU C.</p> 2980 2981 <p>On some targets, the code generator must emit a directive to the assembler or 2982 object file to prevent the assembler and linker from molesting the symbol.</p> 2983 2984 </div> 2985 2986 <!-- ======================================================================= --> 2987 <h3> 2988 <a name="intg_compiler_used"> 2989 The '<tt>llvm.compiler.used</tt>' Global Variable 2990 </a> 2991 </h3> 2992 2993 <div> 2994 2995 <p>The <tt>@llvm.compiler.used</tt> directive is the same as the 2996 <tt>@llvm.used</tt> directive, except that it only prevents the compiler from 2997 touching the symbol. On targets that support it, this allows an intelligent 2998 linker to optimize references to the symbol without being impeded as it would be 2999 by <tt>@llvm.used</tt>.</p> 3000 3001 <p>This is a rare construct that should only be used in rare circumstances, and 3002 should not be exposed to source languages.</p> 3003 3004 </div> 3005 3006 <!-- ======================================================================= --> 3007 <h3> 3008 <a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a> 3009 </h3> 3010 3011 <div> 3012 <pre> 3013 %0 = type { i32, void ()* } 3014 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }] 3015 </pre> 3016 <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. 3017 </p> 3018 3019 </div> 3020 3021 <!-- ======================================================================= --> 3022 <h3> 3023 <a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a> 3024 </h3> 3025 3026 <div> 3027 <pre> 3028 %0 = type { i32, void ()* } 3029 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }] 3030 </pre> 3031 3032 <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. 3033 </p> 3034 3035 </div> 3036 3037 </div> 3038 3039 <!-- *********************************************************************** --> 3040 <h2><a name="instref">Instruction Reference</a></h2> 3041 <!-- *********************************************************************** --> 3042 3043 <div> 3044 3045 <p>The LLVM instruction set consists of several different classifications of 3046 instructions: <a href="#terminators">terminator 3047 instructions</a>, <a href="#binaryops">binary instructions</a>, 3048 <a href="#bitwiseops">bitwise binary instructions</a>, 3049 <a href="#memoryops">memory instructions</a>, and 3050 <a href="#otherops">other instructions</a>.</p> 3051 3052 <!-- ======================================================================= --> 3053 <h3> 3054 <a name="terminators">Terminator Instructions</a> 3055 </h3> 3056 3057 <div> 3058 3059 <p>As mentioned <a href="#functionstructure">previously</a>, every basic block 3060 in a program ends with a "Terminator" instruction, which indicates which 3061 block should be executed after the current block is finished. These 3062 terminator instructions typically yield a '<tt>void</tt>' value: they produce 3063 control flow, not values (the one exception being the 3064 '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p> 3065 3066 <p>The terminator instructions are: 3067 '<a href="#i_ret"><tt>ret</tt></a>', 3068 '<a href="#i_br"><tt>br</tt></a>', 3069 '<a href="#i_switch"><tt>switch</tt></a>', 3070 '<a href="#i_indirectbr"><tt>indirectbr</tt></a>', 3071 '<a href="#i_invoke"><tt>invoke</tt></a>', 3072 '<a href="#i_unwind"><tt>unwind</tt></a>', 3073 '<a href="#i_resume"><tt>resume</tt></a>', and 3074 '<a href="#i_unreachable"><tt>unreachable</tt></a>'.</p> 3075 3076 <!-- _______________________________________________________________________ --> 3077 <h4> 3078 <a name="i_ret">'<tt>ret</tt>' Instruction</a> 3079 </h4> 3080 3081 <div> 3082 3083 <h5>Syntax:</h5> 3084 <pre> 3085 ret <type> <value> <i>; Return a value from a non-void function</i> 3086 ret void <i>; Return from void function</i> 3087 </pre> 3088 3089 <h5>Overview:</h5> 3090 <p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally 3091 a value) from a function back to the caller.</p> 3092 3093 <p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a 3094 value and then causes control flow, and one that just causes control flow to 3095 occur.</p> 3096 3097 <h5>Arguments:</h5> 3098 <p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the 3099 return value. The type of the return value must be a 3100 '<a href="#t_firstclass">first class</a>' type.</p> 3101 3102 <p>A function is not <a href="#wellformed">well formed</a> if it it has a 3103 non-void return type and contains a '<tt>ret</tt>' instruction with no return 3104 value or a return value with a type that does not match its type, or if it 3105 has a void return type and contains a '<tt>ret</tt>' instruction with a 3106 return value.</p> 3107 3108 <h5>Semantics:</h5> 3109 <p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to 3110 the calling function's context. If the caller is a 3111 "<a href="#i_call"><tt>call</tt></a>" instruction, execution continues at the 3112 instruction after the call. If the caller was an 3113 "<a href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at 3114 the beginning of the "normal" destination block. If the instruction returns 3115 a value, that value shall set the call or invoke instruction's return 3116 value.</p> 3117 3118 <h5>Example:</h5> 3119 <pre> 3120 ret i32 5 <i>; Return an integer value of 5</i> 3121 ret void <i>; Return from a void function</i> 3122 ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct of values 4 and 2</i> 3123 </pre> 3124 3125 </div> 3126 <!-- _______________________________________________________________________ --> 3127 <h4> 3128 <a name="i_br">'<tt>br</tt>' Instruction</a> 3129 </h4> 3130 3131 <div> 3132 3133 <h5>Syntax:</h5> 3134 <pre> 3135 br i1 <cond>, label <iftrue>, label <iffalse> 3136 br label <dest> <i>; Unconditional branch</i> 3137 </pre> 3138 3139 <h5>Overview:</h5> 3140 <p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a 3141 different basic block in the current function. There are two forms of this 3142 instruction, corresponding to a conditional branch and an unconditional 3143 branch.</p> 3144 3145 <h5>Arguments:</h5> 3146 <p>The conditional branch form of the '<tt>br</tt>' instruction takes a single 3147 '<tt>i1</tt>' value and two '<tt>label</tt>' values. The unconditional form 3148 of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a 3149 target.</p> 3150 3151 <h5>Semantics:</h5> 3152 <p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>' 3153 argument is evaluated. If the value is <tt>true</tt>, control flows to the 3154 '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>, 3155 control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p> 3156 3157 <h5>Example:</h5> 3158 <pre> 3159 Test: 3160 %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b 3161 br i1 %cond, label %IfEqual, label %IfUnequal 3162 IfEqual: 3163 <a href="#i_ret">ret</a> i32 1 3164 IfUnequal: 3165 <a href="#i_ret">ret</a> i32 0 3166 </pre> 3167 3168 </div> 3169 3170 <!-- _______________________________________________________________________ --> 3171 <h4> 3172 <a name="i_switch">'<tt>switch</tt>' Instruction</a> 3173 </h4> 3174 3175 <div> 3176 3177 <h5>Syntax:</h5> 3178 <pre> 3179 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ] 3180 </pre> 3181 3182 <h5>Overview:</h5> 3183 <p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of 3184 several different places. It is a generalization of the '<tt>br</tt>' 3185 instruction, allowing a branch to occur to one of many possible 3186 destinations.</p> 3187 3188 <h5>Arguments:</h5> 3189 <p>The '<tt>switch</tt>' instruction uses three parameters: an integer 3190 comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, 3191 and an array of pairs of comparison value constants and '<tt>label</tt>'s. 3192 The table is not allowed to contain duplicate constant entries.</p> 3193 3194 <h5>Semantics:</h5> 3195 <p>The <tt>switch</tt> instruction specifies a table of values and 3196 destinations. When the '<tt>switch</tt>' instruction is executed, this table 3197 is searched for the given value. If the value is found, control flow is 3198 transferred to the corresponding destination; otherwise, control flow is 3199 transferred to the default destination.</p> 3200 3201 <h5>Implementation:</h5> 3202 <p>Depending on properties of the target machine and the particular 3203 <tt>switch</tt> instruction, this instruction may be code generated in 3204 different ways. For example, it could be generated as a series of chained 3205 conditional branches or with a lookup table.</p> 3206 3207 <h5>Example:</h5> 3208 <pre> 3209 <i>; Emulate a conditional br instruction</i> 3210 %Val = <a href="#i_zext">zext</a> i1 %value to i32 3211 switch i32 %Val, label %truedest [ i32 0, label %falsedest ] 3212 3213 <i>; Emulate an unconditional br instruction</i> 3214 switch i32 0, label %dest [ ] 3215 3216 <i>; Implement a jump table:</i> 3217 switch i32 %val, label %otherwise [ i32 0, label %onzero 3218 i32 1, label %onone 3219 i32 2, label %ontwo ] 3220 </pre> 3221 3222 </div> 3223 3224 3225 <!-- _______________________________________________________________________ --> 3226 <h4> 3227 <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a> 3228 </h4> 3229 3230 <div> 3231 3232 <h5>Syntax:</h5> 3233 <pre> 3234 indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ] 3235 </pre> 3236 3237 <h5>Overview:</h5> 3238 3239 <p>The '<tt>indirectbr</tt>' instruction implements an indirect branch to a label 3240 within the current function, whose address is specified by 3241 "<tt>address</tt>". Address must be derived from a <a 3242 href="#blockaddress">blockaddress</a> constant.</p> 3243 3244 <h5>Arguments:</h5> 3245 3246 <p>The '<tt>address</tt>' argument is the address of the label to jump to. The 3247 rest of the arguments indicate the full set of possible destinations that the 3248 address may point to. Blocks are allowed to occur multiple times in the 3249 destination list, though this isn't particularly useful.</p> 3250 3251 <p>This destination list is required so that dataflow analysis has an accurate 3252 understanding of the CFG.</p> 3253 3254 <h5>Semantics:</h5> 3255 3256 <p>Control transfers to the block specified in the address argument. All 3257 possible destination blocks must be listed in the label list, otherwise this 3258 instruction has undefined behavior. This implies that jumps to labels 3259 defined in other functions have undefined behavior as well.</p> 3260 3261 <h5>Implementation:</h5> 3262 3263 <p>This is typically implemented with a jump through a register.</p> 3264 3265 <h5>Example:</h5> 3266 <pre> 3267 indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ] 3268 </pre> 3269 3270 </div> 3271 3272 3273 <!-- _______________________________________________________________________ --> 3274 <h4> 3275 <a name="i_invoke">'<tt>invoke</tt>' Instruction</a> 3276 </h4> 3277 3278 <div> 3279 3280 <h5>Syntax:</h5> 3281 <pre> 3282 <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>] 3283 to label <normal label> unwind label <exception label> 3284 </pre> 3285 3286 <h5>Overview:</h5> 3287 <p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified 3288 function, with the possibility of control flow transfer to either the 3289 '<tt>normal</tt>' label or the '<tt>exception</tt>' label. If the callee 3290 function returns with the "<tt><a href="#i_ret">ret</a></tt>" instruction, 3291 control flow will return to the "normal" label. If the callee (or any 3292 indirect callees) returns with the "<a href="#i_unwind"><tt>unwind</tt></a>" 3293 instruction, control is interrupted and continued at the dynamically nearest 3294 "exception" label.</p> 3295 3296 <p>The '<tt>exception</tt>' label is a 3297 <i><a href="ExceptionHandling.html#overview">landing pad</a></i> for the 3298 exception. As such, '<tt>exception</tt>' label is required to have the 3299 "<a href="#i_landingpad"><tt>landingpad</tt></a>" instruction, which contains 3300 the information about about the behavior of the program after unwinding 3301 happens, as its first non-PHI instruction. The restrictions on the 3302 "<tt>landingpad</tt>" instruction's tightly couples it to the 3303 "<tt>invoke</tt>" instruction, so that the important information contained 3304 within the "<tt>landingpad</tt>" instruction can't be lost through normal 3305 code motion.</p> 3306 3307 <h5>Arguments:</h5> 3308 <p>This instruction requires several arguments:</p> 3309 3310 <ol> 3311 <li>The optional "cconv" marker indicates which <a href="#callingconv">calling 3312 convention</a> the call should use. If none is specified, the call 3313 defaults to using C calling conventions.</li> 3314 3315 <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for 3316 return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and 3317 '<tt>inreg</tt>' attributes are valid here.</li> 3318 3319 <li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to 3320 function value being invoked. In most cases, this is a direct function 3321 invocation, but indirect <tt>invoke</tt>s are just as possible, branching 3322 off an arbitrary pointer to function value.</li> 3323 3324 <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a 3325 function to be invoked. </li> 3326 3327 <li>'<tt>function args</tt>': argument list whose types match the function 3328 signature argument types and parameter attributes. All arguments must be 3329 of <a href="#t_firstclass">first class</a> type. If the function 3330 signature indicates the function accepts a variable number of arguments, 3331 the extra arguments can be specified.</li> 3332 3333 <li>'<tt>normal label</tt>': the label reached when the called function 3334 executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li> 3335 3336 <li>'<tt>exception label</tt>': the label reached when a callee returns with 3337 the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li> 3338 3339 <li>The optional <a href="#fnattrs">function attributes</a> list. Only 3340 '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and 3341 '<tt>readnone</tt>' attributes are valid here.</li> 3342 </ol> 3343 3344 <h5>Semantics:</h5> 3345 <p>This instruction is designed to operate as a standard 3346 '<tt><a href="#i_call">call</a></tt>' instruction in most regards. The 3347 primary difference is that it establishes an association with a label, which 3348 is used by the runtime library to unwind the stack.</p> 3349 3350 <p>This instruction is used in languages with destructors to ensure that proper 3351 cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown 3352 exception. Additionally, this is important for implementation of 3353 '<tt>catch</tt>' clauses in high-level languages that support them.</p> 3354 3355 <p>For the purposes of the SSA form, the definition of the value returned by the 3356 '<tt>invoke</tt>' instruction is deemed to occur on the edge from the current 3357 block to the "normal" label. If the callee unwinds then no return value is 3358 available.</p> 3359 3360 <p>Note that the code generator does not yet completely support unwind, and 3361 that the invoke/unwind semantics are likely to change in future versions.</p> 3362 3363 <h5>Example:</h5> 3364 <pre> 3365 %retval = invoke i32 @Test(i32 15) to label %Continue 3366 unwind label %TestCleanup <i>; {i32}:retval set</i> 3367 %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue 3368 unwind label %TestCleanup <i>; {i32}:retval set</i> 3369 </pre> 3370 3371 </div> 3372 3373 <!-- _______________________________________________________________________ --> 3374 3375 <h4> 3376 <a name="i_unwind">'<tt>unwind</tt>' Instruction</a> 3377 </h4> 3378 3379 <div> 3380 3381 <h5>Syntax:</h5> 3382 <pre> 3383 unwind 3384 </pre> 3385 3386 <h5>Overview:</h5> 3387 <p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow 3388 at the first callee in the dynamic call stack which used 3389 an <a href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. 3390 This is primarily used to implement exception handling.</p> 3391 3392 <h5>Semantics:</h5> 3393 <p>The '<tt>unwind</tt>' instruction causes execution of the current function to 3394 immediately halt. The dynamic call stack is then searched for the 3395 first <a href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. 3396 Once found, execution continues at the "exceptional" destination block 3397 specified by the <tt>invoke</tt> instruction. If there is no <tt>invoke</tt> 3398 instruction in the dynamic call chain, undefined behavior results.</p> 3399 3400 <p>Note that the code generator does not yet completely support unwind, and 3401 that the invoke/unwind semantics are likely to change in future versions.</p> 3402 3403 </div> 3404 3405 <!-- _______________________________________________________________________ --> 3406 3407 <h4> 3408 <a name="i_resume">'<tt>resume</tt>' Instruction</a> 3409 </h4> 3410 3411 <div> 3412 3413 <h5>Syntax:</h5> 3414 <pre> 3415 resume <type> <value> 3416 </pre> 3417 3418 <h5>Overview:</h5> 3419 <p>The '<tt>resume</tt>' instruction is a terminator instruction that has no 3420 successors.</p> 3421 3422 <h5>Arguments:</h5> 3423 <p>The '<tt>resume</tt>' instruction requires one argument, which must have the 3424 same type as the result of any '<tt>landingpad</tt>' instruction in the same 3425 function.</p> 3426 3427 <h5>Semantics:</h5> 3428 <p>The '<tt>resume</tt>' instruction resumes propagation of an existing 3429 (in-flight) exception whose unwinding was interrupted with 3430 a <a href="#i_landingpad"><tt>landingpad</tt></a> instruction.</p> 3431 3432 <h5>Example:</h5> 3433 <pre> 3434 resume { i8*, i32 } %exn 3435 </pre> 3436 3437 </div> 3438 3439 <!-- _______________________________________________________________________ --> 3440 3441 <h4> 3442 <a name="i_unreachable">'<tt>unreachable</tt>' Instruction</a> 3443 </h4> 3444 3445 <div> 3446 3447 <h5>Syntax:</h5> 3448 <pre> 3449 unreachable 3450 </pre> 3451 3452 <h5>Overview:</h5> 3453 <p>The '<tt>unreachable</tt>' instruction has no defined semantics. This 3454 instruction is used to inform the optimizer that a particular portion of the 3455 code is not reachable. This can be used to indicate that the code after a 3456 no-return function cannot be reached, and other facts.</p> 3457 3458 <h5>Semantics:</h5> 3459 <p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p> 3460 3461 </div> 3462 3463 </div> 3464 3465 <!-- ======================================================================= --> 3466 <h3> 3467 <a name="binaryops">Binary Operations</a> 3468 </h3> 3469 3470 <div> 3471 3472 <p>Binary operators are used to do most of the computation in a program. They 3473 require two operands of the same type, execute an operation on them, and 3474 produce a single value. The operands might represent multiple data, as is 3475 the case with the <a href="#t_vector">vector</a> data type. The result value 3476 has the same type as its operands.</p> 3477 3478 <p>There are several different binary operators:</p> 3479 3480 <!-- _______________________________________________________________________ --> 3481 <h4> 3482 <a name="i_add">'<tt>add</tt>' Instruction</a> 3483 </h4> 3484 3485 <div> 3486 3487 <h5>Syntax:</h5> 3488 <pre> 3489 <result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3490 <result> = add nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3491 <result> = add nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3492 <result> = add nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3493 </pre> 3494 3495 <h5>Overview:</h5> 3496 <p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p> 3497 3498 <h5>Arguments:</h5> 3499 <p>The two arguments to the '<tt>add</tt>' instruction must 3500 be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of 3501 integer values. Both arguments must have identical types.</p> 3502 3503 <h5>Semantics:</h5> 3504 <p>The value produced is the integer sum of the two operands.</p> 3505 3506 <p>If the sum has unsigned overflow, the result returned is the mathematical 3507 result modulo 2<sup>n</sup>, where n is the bit width of the result.</p> 3508 3509 <p>Because LLVM integers use a two's complement representation, this instruction 3510 is appropriate for both signed and unsigned integers.</p> 3511 3512 <p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" 3513 and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or 3514 <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt> 3515 is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow, 3516 respectively, occurs.</p> 3517 3518 <h5>Example:</h5> 3519 <pre> 3520 <result> = add i32 4, %var <i>; yields {i32}:result = 4 + %var</i> 3521 </pre> 3522 3523 </div> 3524 3525 <!-- _______________________________________________________________________ --> 3526 <h4> 3527 <a name="i_fadd">'<tt>fadd</tt>' Instruction</a> 3528 </h4> 3529 3530 <div> 3531 3532 <h5>Syntax:</h5> 3533 <pre> 3534 <result> = fadd <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3535 </pre> 3536 3537 <h5>Overview:</h5> 3538 <p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p> 3539 3540 <h5>Arguments:</h5> 3541 <p>The two arguments to the '<tt>fadd</tt>' instruction must be 3542 <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of 3543 floating point values. Both arguments must have identical types.</p> 3544 3545 <h5>Semantics:</h5> 3546 <p>The value produced is the floating point sum of the two operands.</p> 3547 3548 <h5>Example:</h5> 3549 <pre> 3550 <result> = fadd float 4.0, %var <i>; yields {float}:result = 4.0 + %var</i> 3551 </pre> 3552 3553 </div> 3554 3555 <!-- _______________________________________________________________________ --> 3556 <h4> 3557 <a name="i_sub">'<tt>sub</tt>' Instruction</a> 3558 </h4> 3559 3560 <div> 3561 3562 <h5>Syntax:</h5> 3563 <pre> 3564 <result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3565 <result> = sub nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3566 <result> = sub nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3567 <result> = sub nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3568 </pre> 3569 3570 <h5>Overview:</h5> 3571 <p>The '<tt>sub</tt>' instruction returns the difference of its two 3572 operands.</p> 3573 3574 <p>Note that the '<tt>sub</tt>' instruction is used to represent the 3575 '<tt>neg</tt>' instruction present in most other intermediate 3576 representations.</p> 3577 3578 <h5>Arguments:</h5> 3579 <p>The two arguments to the '<tt>sub</tt>' instruction must 3580 be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of 3581 integer values. Both arguments must have identical types.</p> 3582 3583 <h5>Semantics:</h5> 3584 <p>The value produced is the integer difference of the two operands.</p> 3585 3586 <p>If the difference has unsigned overflow, the result returned is the 3587 mathematical result modulo 2<sup>n</sup>, where n is the bit width of the 3588 result.</p> 3589 3590 <p>Because LLVM integers use a two's complement representation, this instruction 3591 is appropriate for both signed and unsigned integers.</p> 3592 3593 <p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" 3594 and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or 3595 <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt> 3596 is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow, 3597 respectively, occurs.</p> 3598 3599 <h5>Example:</h5> 3600 <pre> 3601 <result> = sub i32 4, %var <i>; yields {i32}:result = 4 - %var</i> 3602 <result> = sub i32 0, %val <i>; yields {i32}:result = -%var</i> 3603 </pre> 3604 3605 </div> 3606 3607 <!-- _______________________________________________________________________ --> 3608 <h4> 3609 <a name="i_fsub">'<tt>fsub</tt>' Instruction</a> 3610 </h4> 3611 3612 <div> 3613 3614 <h5>Syntax:</h5> 3615 <pre> 3616 <result> = fsub <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3617 </pre> 3618 3619 <h5>Overview:</h5> 3620 <p>The '<tt>fsub</tt>' instruction returns the difference of its two 3621 operands.</p> 3622 3623 <p>Note that the '<tt>fsub</tt>' instruction is used to represent the 3624 '<tt>fneg</tt>' instruction present in most other intermediate 3625 representations.</p> 3626 3627 <h5>Arguments:</h5> 3628 <p>The two arguments to the '<tt>fsub</tt>' instruction must be 3629 <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of 3630 floating point values. Both arguments must have identical types.</p> 3631 3632 <h5>Semantics:</h5> 3633 <p>The value produced is the floating point difference of the two operands.</p> 3634 3635 <h5>Example:</h5> 3636 <pre> 3637 <result> = fsub float 4.0, %var <i>; yields {float}:result = 4.0 - %var</i> 3638 <result> = fsub float -0.0, %val <i>; yields {float}:result = -%var</i> 3639 </pre> 3640 3641 </div> 3642 3643 <!-- _______________________________________________________________________ --> 3644 <h4> 3645 <a name="i_mul">'<tt>mul</tt>' Instruction</a> 3646 </h4> 3647 3648 <div> 3649 3650 <h5>Syntax:</h5> 3651 <pre> 3652 <result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3653 <result> = mul nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3654 <result> = mul nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3655 <result> = mul nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3656 </pre> 3657 3658 <h5>Overview:</h5> 3659 <p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p> 3660 3661 <h5>Arguments:</h5> 3662 <p>The two arguments to the '<tt>mul</tt>' instruction must 3663 be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of 3664 integer values. Both arguments must have identical types.</p> 3665 3666 <h5>Semantics:</h5> 3667 <p>The value produced is the integer product of the two operands.</p> 3668 3669 <p>If the result of the multiplication has unsigned overflow, the result 3670 returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit 3671 width of the result.</p> 3672 3673 <p>Because LLVM integers use a two's complement representation, and the result 3674 is the same width as the operands, this instruction returns the correct 3675 result for both signed and unsigned integers. If a full product 3676 (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should 3677 be sign-extended or zero-extended as appropriate to the width of the full 3678 product.</p> 3679 3680 <p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap" 3681 and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or 3682 <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt> 3683 is a <a href="#trapvalues">trap value</a> if unsigned and/or signed overflow, 3684 respectively, occurs.</p> 3685 3686 <h5>Example:</h5> 3687 <pre> 3688 <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i> 3689 </pre> 3690 3691 </div> 3692 3693 <!-- _______________________________________________________________________ --> 3694 <h4> 3695 <a name="i_fmul">'<tt>fmul</tt>' Instruction</a> 3696 </h4> 3697 3698 <div> 3699 3700 <h5>Syntax:</h5> 3701 <pre> 3702 <result> = fmul <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3703 </pre> 3704 3705 <h5>Overview:</h5> 3706 <p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p> 3707 3708 <h5>Arguments:</h5> 3709 <p>The two arguments to the '<tt>fmul</tt>' instruction must be 3710 <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of 3711 floating point values. Both arguments must have identical types.</p> 3712 3713 <h5>Semantics:</h5> 3714 <p>The value produced is the floating point product of the two operands.</p> 3715 3716 <h5>Example:</h5> 3717 <pre> 3718 <result> = fmul float 4.0, %var <i>; yields {float}:result = 4.0 * %var</i> 3719 </pre> 3720 3721 </div> 3722 3723 <!-- _______________________________________________________________________ --> 3724 <h4> 3725 <a name="i_udiv">'<tt>udiv</tt>' Instruction</a> 3726 </h4> 3727 3728 <div> 3729 3730 <h5>Syntax:</h5> 3731 <pre> 3732 <result> = udiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3733 <result> = udiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3734 </pre> 3735 3736 <h5>Overview:</h5> 3737 <p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p> 3738 3739 <h5>Arguments:</h5> 3740 <p>The two arguments to the '<tt>udiv</tt>' instruction must be 3741 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 3742 values. Both arguments must have identical types.</p> 3743 3744 <h5>Semantics:</h5> 3745 <p>The value produced is the unsigned integer quotient of the two operands.</p> 3746 3747 <p>Note that unsigned integer division and signed integer division are distinct 3748 operations; for signed integer division, use '<tt>sdiv</tt>'.</p> 3749 3750 <p>Division by zero leads to undefined behavior.</p> 3751 3752 <p>If the <tt>exact</tt> keyword is present, the result value of the 3753 <tt>udiv</tt> is a <a href="#trapvalues">trap value</a> if %op1 is not a 3754 multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p> 3755 3756 3757 <h5>Example:</h5> 3758 <pre> 3759 <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> 3760 </pre> 3761 3762 </div> 3763 3764 <!-- _______________________________________________________________________ --> 3765 <h4> 3766 <a name="i_sdiv">'<tt>sdiv</tt>' Instruction</a> 3767 </h4> 3768 3769 <div> 3770 3771 <h5>Syntax:</h5> 3772 <pre> 3773 <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3774 <result> = sdiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3775 </pre> 3776 3777 <h5>Overview:</h5> 3778 <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p> 3779 3780 <h5>Arguments:</h5> 3781 <p>The two arguments to the '<tt>sdiv</tt>' instruction must be 3782 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 3783 values. Both arguments must have identical types.</p> 3784 3785 <h5>Semantics:</h5> 3786 <p>The value produced is the signed integer quotient of the two operands rounded 3787 towards zero.</p> 3788 3789 <p>Note that signed integer division and unsigned integer division are distinct 3790 operations; for unsigned integer division, use '<tt>udiv</tt>'.</p> 3791 3792 <p>Division by zero leads to undefined behavior. Overflow also leads to 3793 undefined behavior; this is a rare case, but can occur, for example, by doing 3794 a 32-bit division of -2147483648 by -1.</p> 3795 3796 <p>If the <tt>exact</tt> keyword is present, the result value of the 3797 <tt>sdiv</tt> is a <a href="#trapvalues">trap value</a> if the result would 3798 be rounded.</p> 3799 3800 <h5>Example:</h5> 3801 <pre> 3802 <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i> 3803 </pre> 3804 3805 </div> 3806 3807 <!-- _______________________________________________________________________ --> 3808 <h4> 3809 <a name="i_fdiv">'<tt>fdiv</tt>' Instruction</a> 3810 </h4> 3811 3812 <div> 3813 3814 <h5>Syntax:</h5> 3815 <pre> 3816 <result> = fdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3817 </pre> 3818 3819 <h5>Overview:</h5> 3820 <p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p> 3821 3822 <h5>Arguments:</h5> 3823 <p>The two arguments to the '<tt>fdiv</tt>' instruction must be 3824 <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of 3825 floating point values. Both arguments must have identical types.</p> 3826 3827 <h5>Semantics:</h5> 3828 <p>The value produced is the floating point quotient of the two operands.</p> 3829 3830 <h5>Example:</h5> 3831 <pre> 3832 <result> = fdiv float 4.0, %var <i>; yields {float}:result = 4.0 / %var</i> 3833 </pre> 3834 3835 </div> 3836 3837 <!-- _______________________________________________________________________ --> 3838 <h4> 3839 <a name="i_urem">'<tt>urem</tt>' Instruction</a> 3840 </h4> 3841 3842 <div> 3843 3844 <h5>Syntax:</h5> 3845 <pre> 3846 <result> = urem <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3847 </pre> 3848 3849 <h5>Overview:</h5> 3850 <p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned 3851 division of its two arguments.</p> 3852 3853 <h5>Arguments:</h5> 3854 <p>The two arguments to the '<tt>urem</tt>' instruction must be 3855 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 3856 values. Both arguments must have identical types.</p> 3857 3858 <h5>Semantics:</h5> 3859 <p>This instruction returns the unsigned integer <i>remainder</i> of a division. 3860 This instruction always performs an unsigned division to get the 3861 remainder.</p> 3862 3863 <p>Note that unsigned integer remainder and signed integer remainder are 3864 distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p> 3865 3866 <p>Taking the remainder of a division by zero leads to undefined behavior.</p> 3867 3868 <h5>Example:</h5> 3869 <pre> 3870 <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> 3871 </pre> 3872 3873 </div> 3874 3875 <!-- _______________________________________________________________________ --> 3876 <h4> 3877 <a name="i_srem">'<tt>srem</tt>' Instruction</a> 3878 </h4> 3879 3880 <div> 3881 3882 <h5>Syntax:</h5> 3883 <pre> 3884 <result> = srem <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3885 </pre> 3886 3887 <h5>Overview:</h5> 3888 <p>The '<tt>srem</tt>' instruction returns the remainder from the signed 3889 division of its two operands. This instruction can also take 3890 <a href="#t_vector">vector</a> versions of the values in which case the 3891 elements must be integers.</p> 3892 3893 <h5>Arguments:</h5> 3894 <p>The two arguments to the '<tt>srem</tt>' instruction must be 3895 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 3896 values. Both arguments must have identical types.</p> 3897 3898 <h5>Semantics:</h5> 3899 <p>This instruction returns the <i>remainder</i> of a division (where the result 3900 is either zero or has the same sign as the dividend, <tt>op1</tt>), not the 3901 <i>modulo</i> operator (where the result is either zero or has the same sign 3902 as the divisor, <tt>op2</tt>) of a value. 3903 For more information about the difference, 3904 see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The 3905 Math Forum</a>. For a table of how this is implemented in various languages, 3906 please see <a href="http://en.wikipedia.org/wiki/Modulo_operation"> 3907 Wikipedia: modulo operation</a>.</p> 3908 3909 <p>Note that signed integer remainder and unsigned integer remainder are 3910 distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p> 3911 3912 <p>Taking the remainder of a division by zero leads to undefined behavior. 3913 Overflow also leads to undefined behavior; this is a rare case, but can 3914 occur, for example, by taking the remainder of a 32-bit division of 3915 -2147483648 by -1. (The remainder doesn't actually overflow, but this rule 3916 lets srem be implemented using instructions that return both the result of 3917 the division and the remainder.)</p> 3918 3919 <h5>Example:</h5> 3920 <pre> 3921 <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i> 3922 </pre> 3923 3924 </div> 3925 3926 <!-- _______________________________________________________________________ --> 3927 <h4> 3928 <a name="i_frem">'<tt>frem</tt>' Instruction</a> 3929 </h4> 3930 3931 <div> 3932 3933 <h5>Syntax:</h5> 3934 <pre> 3935 <result> = frem <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3936 </pre> 3937 3938 <h5>Overview:</h5> 3939 <p>The '<tt>frem</tt>' instruction returns the remainder from the division of 3940 its two operands.</p> 3941 3942 <h5>Arguments:</h5> 3943 <p>The two arguments to the '<tt>frem</tt>' instruction must be 3944 <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of 3945 floating point values. Both arguments must have identical types.</p> 3946 3947 <h5>Semantics:</h5> 3948 <p>This instruction returns the <i>remainder</i> of a division. The remainder 3949 has the same sign as the dividend.</p> 3950 3951 <h5>Example:</h5> 3952 <pre> 3953 <result> = frem float 4.0, %var <i>; yields {float}:result = 4.0 % %var</i> 3954 </pre> 3955 3956 </div> 3957 3958 </div> 3959 3960 <!-- ======================================================================= --> 3961 <h3> 3962 <a name="bitwiseops">Bitwise Binary Operations</a> 3963 </h3> 3964 3965 <div> 3966 3967 <p>Bitwise binary operators are used to do various forms of bit-twiddling in a 3968 program. They are generally very efficient instructions and can commonly be 3969 strength reduced from other instructions. They require two operands of the 3970 same type, execute an operation on them, and produce a single value. The 3971 resulting value is the same type as its operands.</p> 3972 3973 <!-- _______________________________________________________________________ --> 3974 <h4> 3975 <a name="i_shl">'<tt>shl</tt>' Instruction</a> 3976 </h4> 3977 3978 <div> 3979 3980 <h5>Syntax:</h5> 3981 <pre> 3982 <result> = shl <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3983 <result> = shl nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3984 <result> = shl nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3985 <result> = shl nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i> 3986 </pre> 3987 3988 <h5>Overview:</h5> 3989 <p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left 3990 a specified number of bits.</p> 3991 3992 <h5>Arguments:</h5> 3993 <p>Both arguments to the '<tt>shl</tt>' instruction must be the 3994 same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of 3995 integer type. '<tt>op2</tt>' is treated as an unsigned value.</p> 3996 3997 <h5>Semantics:</h5> 3998 <p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod 3999 2<sup>n</sup>, where <tt>n</tt> is the width of the result. If <tt>op2</tt> 4000 is (statically or dynamically) negative or equal to or larger than the number 4001 of bits in <tt>op1</tt>, the result is undefined. If the arguments are 4002 vectors, each vector element of <tt>op1</tt> is shifted by the corresponding 4003 shift amount in <tt>op2</tt>.</p> 4004 4005 <p>If the <tt>nuw</tt> keyword is present, then the shift produces a 4006 <a href="#trapvalues">trap value</a> if it shifts out any non-zero bits. If 4007 the <tt>nsw</tt> keyword is present, then the shift produces a 4008 <a href="#trapvalues">trap value</a> if it shifts out any bits that disagree 4009 with the resultant sign bit. As such, NUW/NSW have the same semantics as 4010 they would if the shift were expressed as a mul instruction with the same 4011 nsw/nuw bits in (mul %op1, (shl 1, %op2)).</p> 4012 4013 <h5>Example:</h5> 4014 <pre> 4015 <result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i> 4016 <result> = shl i32 4, 2 <i>; yields {i32}: 16</i> 4017 <result> = shl i32 1, 10 <i>; yields {i32}: 1024</i> 4018 <result> = shl i32 1, 32 <i>; undefined</i> 4019 <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 2, i32 4></i> 4020 </pre> 4021 4022 </div> 4023 4024 <!-- _______________________________________________________________________ --> 4025 <h4> 4026 <a name="i_lshr">'<tt>lshr</tt>' Instruction</a> 4027 </h4> 4028 4029 <div> 4030 4031 <h5>Syntax:</h5> 4032 <pre> 4033 <result> = lshr <ty> <op1>, <op2> <i>; yields {ty}:result</i> 4034 <result> = lshr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> 4035 </pre> 4036 4037 <h5>Overview:</h5> 4038 <p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first 4039 operand shifted to the right a specified number of bits with zero fill.</p> 4040 4041 <h5>Arguments:</h5> 4042 <p>Both arguments to the '<tt>lshr</tt>' instruction must be the same 4043 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 4044 type. '<tt>op2</tt>' is treated as an unsigned value.</p> 4045 4046 <h5>Semantics:</h5> 4047 <p>This instruction always performs a logical shift right operation. The most 4048 significant bits of the result will be filled with zero bits after the shift. 4049 If <tt>op2</tt> is (statically or dynamically) equal to or larger than the 4050 number of bits in <tt>op1</tt>, the result is undefined. If the arguments are 4051 vectors, each vector element of <tt>op1</tt> is shifted by the corresponding 4052 shift amount in <tt>op2</tt>.</p> 4053 4054 <p>If the <tt>exact</tt> keyword is present, the result value of the 4055 <tt>lshr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits 4056 shifted out are non-zero.</p> 4057 4058 4059 <h5>Example:</h5> 4060 <pre> 4061 <result> = lshr i32 4, 1 <i>; yields {i32}:result = 2</i> 4062 <result> = lshr i32 4, 2 <i>; yields {i32}:result = 1</i> 4063 <result> = lshr i8 4, 3 <i>; yields {i8}:result = 0</i> 4064 <result> = lshr i8 -2, 1 <i>; yields {i8}:result = 0x7FFFFFFF </i> 4065 <result> = lshr i32 1, 32 <i>; undefined</i> 4066 <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> <i>; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1></i> 4067 </pre> 4068 4069 </div> 4070 4071 <!-- _______________________________________________________________________ --> 4072 <h4> 4073 <a name="i_ashr">'<tt>ashr</tt>' Instruction</a> 4074 </h4> 4075 4076 <div> 4077 4078 <h5>Syntax:</h5> 4079 <pre> 4080 <result> = ashr <ty> <op1>, <op2> <i>; yields {ty}:result</i> 4081 <result> = ashr exact <ty> <op1>, <op2> <i>; yields {ty}:result</i> 4082 </pre> 4083 4084 <h5>Overview:</h5> 4085 <p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first 4086 operand shifted to the right a specified number of bits with sign 4087 extension.</p> 4088 4089 <h5>Arguments:</h5> 4090 <p>Both arguments to the '<tt>ashr</tt>' instruction must be the same 4091 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 4092 type. '<tt>op2</tt>' is treated as an unsigned value.</p> 4093 4094 <h5>Semantics:</h5> 4095 <p>This instruction always performs an arithmetic shift right operation, The 4096 most significant bits of the result will be filled with the sign bit 4097 of <tt>op1</tt>. If <tt>op2</tt> is (statically or dynamically) equal to or 4098 larger than the number of bits in <tt>op1</tt>, the result is undefined. If 4099 the arguments are vectors, each vector element of <tt>op1</tt> is shifted by 4100 the corresponding shift amount in <tt>op2</tt>.</p> 4101 4102 <p>If the <tt>exact</tt> keyword is present, the result value of the 4103 <tt>ashr</tt> is a <a href="#trapvalues">trap value</a> if any of the bits 4104 shifted out are non-zero.</p> 4105 4106 <h5>Example:</h5> 4107 <pre> 4108 <result> = ashr i32 4, 1 <i>; yields {i32}:result = 2</i> 4109 <result> = ashr i32 4, 2 <i>; yields {i32}:result = 1</i> 4110 <result> = ashr i8 4, 3 <i>; yields {i8}:result = 0</i> 4111 <result> = ashr i8 -2, 1 <i>; yields {i8}:result = -1</i> 4112 <result> = ashr i32 1, 32 <i>; undefined</i> 4113 <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> <i>; yields: result=<2 x i32> < i32 -1, i32 0></i> 4114 </pre> 4115 4116 </div> 4117 4118 <!-- _______________________________________________________________________ --> 4119 <h4> 4120 <a name="i_and">'<tt>and</tt>' Instruction</a> 4121 </h4> 4122 4123 <div> 4124 4125 <h5>Syntax:</h5> 4126 <pre> 4127 <result> = and <ty> <op1>, <op2> <i>; yields {ty}:result</i> 4128 </pre> 4129 4130 <h5>Overview:</h5> 4131 <p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two 4132 operands.</p> 4133 4134 <h5>Arguments:</h5> 4135 <p>The two arguments to the '<tt>and</tt>' instruction must be 4136 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 4137 values. Both arguments must have identical types.</p> 4138 4139 <h5>Semantics:</h5> 4140 <p>The truth table used for the '<tt>and</tt>' instruction is:</p> 4141 4142 <table border="1" cellspacing="0" cellpadding="4"> 4143 <tbody> 4144 <tr> 4145 <td>In0</td> 4146 <td>In1</td> 4147 <td>Out</td> 4148 </tr> 4149 <tr> 4150 <td>0</td> 4151 <td>0</td> 4152 <td>0</td> 4153 </tr> 4154 <tr> 4155 <td>0</td> 4156 <td>1</td> 4157 <td>0</td> 4158 </tr> 4159 <tr> 4160 <td>1</td> 4161 <td>0</td> 4162 <td>0</td> 4163 </tr> 4164 <tr> 4165 <td>1</td> 4166 <td>1</td> 4167 <td>1</td> 4168 </tr> 4169 </tbody> 4170 </table> 4171 4172 <h5>Example:</h5> 4173 <pre> 4174 <result> = and i32 4, %var <i>; yields {i32}:result = 4 & %var</i> 4175 <result> = and i32 15, 40 <i>; yields {i32}:result = 8</i> 4176 <result> = and i32 4, 8 <i>; yields {i32}:result = 0</i> 4177 </pre> 4178 </div> 4179 <!-- _______________________________________________________________________ --> 4180 <h4> 4181 <a name="i_or">'<tt>or</tt>' Instruction</a> 4182 </h4> 4183 4184 <div> 4185 4186 <h5>Syntax:</h5> 4187 <pre> 4188 <result> = or <ty> <op1>, <op2> <i>; yields {ty}:result</i> 4189 </pre> 4190 4191 <h5>Overview:</h5> 4192 <p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its 4193 two operands.</p> 4194 4195 <h5>Arguments:</h5> 4196 <p>The two arguments to the '<tt>or</tt>' instruction must be 4197 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 4198 values. Both arguments must have identical types.</p> 4199 4200 <h5>Semantics:</h5> 4201 <p>The truth table used for the '<tt>or</tt>' instruction is:</p> 4202 4203 <table border="1" cellspacing="0" cellpadding="4"> 4204 <tbody> 4205 <tr> 4206 <td>In0</td> 4207 <td>In1</td> 4208 <td>Out</td> 4209 </tr> 4210 <tr> 4211 <td>0</td> 4212 <td>0</td> 4213 <td>0</td> 4214 </tr> 4215 <tr> 4216 <td>0</td> 4217 <td>1</td> 4218 <td>1</td> 4219 </tr> 4220 <tr> 4221 <td>1</td> 4222 <td>0</td> 4223 <td>1</td> 4224 </tr> 4225 <tr> 4226 <td>1</td> 4227 <td>1</td> 4228 <td>1</td> 4229 </tr> 4230 </tbody> 4231 </table> 4232 4233 <h5>Example:</h5> 4234 <pre> 4235 <result> = or i32 4, %var <i>; yields {i32}:result = 4 | %var</i> 4236 <result> = or i32 15, 40 <i>; yields {i32}:result = 47</i> 4237 <result> = or i32 4, 8 <i>; yields {i32}:result = 12</i> 4238 </pre> 4239 4240 </div> 4241 4242 <!-- _______________________________________________________________________ --> 4243 <h4> 4244 <a name="i_xor">'<tt>xor</tt>' Instruction</a> 4245 </h4> 4246 4247 <div> 4248 4249 <h5>Syntax:</h5> 4250 <pre> 4251 <result> = xor <ty> <op1>, <op2> <i>; yields {ty}:result</i> 4252 </pre> 4253 4254 <h5>Overview:</h5> 4255 <p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of 4256 its two operands. The <tt>xor</tt> is used to implement the "one's 4257 complement" operation, which is the "~" operator in C.</p> 4258 4259 <h5>Arguments:</h5> 4260 <p>The two arguments to the '<tt>xor</tt>' instruction must be 4261 <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer 4262 values. Both arguments must have identical types.</p> 4263 4264 <h5>Semantics:</h5> 4265 <p>The truth table used for the '<tt>xor</tt>' instruction is:</p> 4266 4267 <table border="1" cellspacing="0" cellpadding="4"> 4268 <tbody> 4269 <tr> 4270 <td>In0</td> 4271 <td>In1</td> 4272 <td>Out</td> 4273 </tr> 4274 <tr> 4275 <td>0</td> 4276 <td>0</td> 4277 <td>0</td> 4278 </tr> 4279 <tr> 4280 <td>0</td> 4281 <td>1</td> 4282 <td>1</td> 4283 </tr> 4284 <tr> 4285 <td>1</td> 4286 <td>0</td> 4287 <td>1</td> 4288 </tr> 4289 <tr> 4290 <td>1</td> 4291 <td>1</td> 4292 <td>0</td> 4293 </tr> 4294 </tbody> 4295 </table> 4296 4297 <h5>Example:</h5> 4298 <pre> 4299 <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i> 4300 <result> = xor i32 15, 40 <i>; yields {i32}:result = 39</i> 4301 <result> = xor i32 4, 8 <i>; yields {i32}:result = 12</i> 4302 <result> = xor i32 %V, -1 <i>; yields {i32}:result = ~%V</i> 4303 </pre> 4304 4305 </div> 4306 4307 </div> 4308 4309 <!-- ======================================================================= --> 4310 <h3> 4311 <a name="vectorops">Vector Operations</a> 4312 </h3> 4313 4314 <div> 4315 4316 <p>LLVM supports several instructions to represent vector operations in a 4317 target-independent manner. These instructions cover the element-access and 4318 vector-specific operations needed to process vectors effectively. While LLVM 4319 does directly support these vector operations, many sophisticated algorithms 4320 will want to use target-specific intrinsics to take full advantage of a 4321 specific target.</p> 4322 4323 <!-- _______________________________________________________________________ --> 4324 <h4> 4325 <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a> 4326 </h4> 4327 4328 <div> 4329 4330 <h5>Syntax:</h5> 4331 <pre> 4332 <result> = extractelement <n x <ty>> <val>, i32 <idx> <i>; yields <ty></i> 4333 </pre> 4334 4335 <h5>Overview:</h5> 4336 <p>The '<tt>extractelement</tt>' instruction extracts a single scalar element 4337 from a vector at a specified index.</p> 4338 4339 4340 <h5>Arguments:</h5> 4341 <p>The first operand of an '<tt>extractelement</tt>' instruction is a value 4342 of <a href="#t_vector">vector</a> type. The second operand is an index 4343 indicating the position from which to extract the element. The index may be 4344 a variable.</p> 4345 4346 <h5>Semantics:</h5> 4347 <p>The result is a scalar of the same type as the element type of 4348 <tt>val</tt>. Its value is the value at position <tt>idx</tt> of 4349 <tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the 4350 results are undefined.</p> 4351 4352 <h5>Example:</h5> 4353 <pre> 4354 <result> = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i> 4355 </pre> 4356 4357 </div> 4358 4359 <!-- _______________________________________________________________________ --> 4360 <h4> 4361 <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a> 4362 </h4> 4363 4364 <div> 4365 4366 <h5>Syntax:</h5> 4367 <pre> 4368 <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx> <i>; yields <n x <ty>></i> 4369 </pre> 4370 4371 <h5>Overview:</h5> 4372 <p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a 4373 vector at a specified index.</p> 4374 4375 <h5>Arguments:</h5> 4376 <p>The first operand of an '<tt>insertelement</tt>' instruction is a value 4377 of <a href="#t_vector">vector</a> type. The second operand is a scalar value 4378 whose type must equal the element type of the first operand. The third 4379 operand is an index indicating the position at which to insert the value. 4380 The index may be a variable.</p> 4381 4382 <h5>Semantics:</h5> 4383 <p>The result is a vector of the same type as <tt>val</tt>. Its element values 4384 are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the 4385 value <tt>elt</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the 4386 results are undefined.</p> 4387 4388 <h5>Example:</h5> 4389 <pre> 4390 <result> = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i> 4391 </pre> 4392 4393 </div> 4394 4395 <!-- _______________________________________________________________________ --> 4396 <h4> 4397 <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a> 4398 </h4> 4399 4400 <div> 4401 4402 <h5>Syntax:</h5> 4403 <pre> 4404 <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> <i>; yields <m x <ty>></i> 4405 </pre> 4406 4407 <h5>Overview:</h5> 4408 <p>The '<tt>shufflevector</tt>' instruction constructs a permutation of elements 4409 from two input vectors, returning a vector with the same element type as the 4410 input and length that is the same as the shuffle mask.</p> 4411 4412 <h5>Arguments:</h5> 4413 <p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors 4414 with types that match each other. The third argument is a shuffle mask whose 4415 element type is always 'i32'. The result of the instruction is a vector 4416 whose length is the same as the shuffle mask and whose element type is the 4417 same as the element type of the first two operands.</p> 4418 4419 <p>The shuffle mask operand is required to be a constant vector with either 4420 constant integer or undef values.</p> 4421 4422 <h5>Semantics:</h5> 4423 <p>The elements of the two input vectors are numbered from left to right across 4424 both of the vectors. The shuffle mask operand specifies, for each element of 4425 the result vector, which element of the two input vectors the result element 4426 gets. The element selector may be undef (meaning "don't care") and the 4427 second operand may be undef if performing a shuffle from only one vector.</p> 4428 4429 <h5>Example:</h5> 4430 <pre> 4431 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 4432 <4 x i32> <i32 0, i32 4, i32 1, i32 5> <i>; yields <4 x i32></i> 4433 <result> = shufflevector <4 x i32> %v1, <4 x i32> undef, 4434 <4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i> - Identity shuffle. 4435 <result> = shufflevector <8 x i32> %v1, <8 x i32> undef, 4436 <4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i> 4437 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 4438 <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> 4439 </pre> 4440 4441 </div> 4442 4443 </div> 4444 4445 <!-- ======================================================================= --> 4446 <h3> 4447 <a name="aggregateops">Aggregate Operations</a> 4448 </h3> 4449 4450 <div> 4451 4452 <p>LLVM supports several instructions for working with 4453 <a href="#t_aggregate">aggregate</a> values.</p> 4454 4455 <!-- _______________________________________________________________________ --> 4456 <h4> 4457 <a name="i_extractvalue">'<tt>extractvalue</tt>' Instruction</a> 4458 </h4> 4459 4460 <div> 4461 4462 <h5>Syntax:</h5> 4463 <pre> 4464 <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}* 4465 </pre> 4466 4467 <h5>Overview:</h5> 4468 <p>The '<tt>extractvalue</tt>' instruction extracts the value of a member field 4469 from an <a href="#t_aggregate">aggregate</a> value.</p> 4470 4471 <h5>Arguments:</h5> 4472 <p>The first operand of an '<tt>extractvalue</tt>' instruction is a value 4473 of <a href="#t_struct">struct</a> or 4474 <a href="#t_array">array</a> type. The operands are constant indices to 4475 specify which value to extract in a similar manner as indices in a 4476 '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p> 4477 <p>The major differences to <tt>getelementptr</tt> indexing are:</p> 4478 <ul> 4479 <li>Since the value being indexed is not a pointer, the first index is 4480 omitted and assumed to be zero.</li> 4481 <li>At least one index must be specified.</li> 4482 <li>Not only struct indices but also array indices must be in 4483 bounds.</li> 4484 </ul> 4485 4486 <h5>Semantics:</h5> 4487 <p>The result is the value at the position in the aggregate specified by the 4488 index operands.</p> 4489 4490 <h5>Example:</h5> 4491 <pre> 4492 <result> = extractvalue {i32, float} %agg, 0 <i>; yields i32</i> 4493 </pre> 4494 4495 </div> 4496 4497 <!-- _______________________________________________________________________ --> 4498 <h4> 4499 <a name="i_insertvalue">'<tt>insertvalue</tt>' Instruction</a> 4500 </h4> 4501 4502 <div> 4503 4504 <h5>Syntax:</h5> 4505 <pre> 4506 <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* <i>; yields <aggregate type></i> 4507 </pre> 4508 4509 <h5>Overview:</h5> 4510 <p>The '<tt>insertvalue</tt>' instruction inserts a value into a member field 4511 in an <a href="#t_aggregate">aggregate</a> value.</p> 4512 4513 <h5>Arguments:</h5> 4514 <p>The first operand of an '<tt>insertvalue</tt>' instruction is a value 4515 of <a href="#t_struct">struct</a> or 4516 <a href="#t_array">array</a> type. The second operand is a first-class 4517 value to insert. The following operands are constant indices indicating 4518 the position at which to insert the value in a similar manner as indices in a 4519 '<tt><a href="#i_extractvalue">extractvalue</a></tt>' instruction. The 4520 value to insert must have the same type as the value identified by the 4521 indices.</p> 4522 4523 <h5>Semantics:</h5> 4524 <p>The result is an aggregate of the same type as <tt>val</tt>. Its value is 4525 that of <tt>val</tt> except that the value at the position specified by the 4526 indices is that of <tt>elt</tt>.</p> 4527 4528 <h5>Example:</h5> 4529 <pre> 4530 %agg1 = insertvalue {i32, float} undef, i32 1, 0 <i>; yields {i32 1, float undef}</i> 4531 %agg2 = insertvalue {i32, float} %agg1, float %val, 1 <i>; yields {i32 1, float %val}</i> 4532 %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0 <i>; yields {i32 1, float %val}</i> 4533 </pre> 4534 4535 </div> 4536 4537 </div> 4538 4539 <!-- ======================================================================= --> 4540 <h3> 4541 <a name="memoryops">Memory Access and Addressing Operations</a> 4542 </h3> 4543 4544 <div> 4545 4546 <p>A key design point of an SSA-based representation is how it represents 4547 memory. In LLVM, no memory locations are in SSA form, which makes things 4548 very simple. This section describes how to read, write, and allocate 4549 memory in LLVM.</p> 4550 4551 <!-- _______________________________________________________________________ --> 4552 <h4> 4553 <a name="i_alloca">'<tt>alloca</tt>' Instruction</a> 4554 </h4> 4555 4556 <div> 4557 4558 <h5>Syntax:</h5> 4559 <pre> 4560 <result> = alloca <type>[, <ty> <NumElements>][, align <alignment>] <i>; yields {type*}:result</i> 4561 </pre> 4562 4563 <h5>Overview:</h5> 4564 <p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the 4565 currently executing function, to be automatically released when this function 4566 returns to its caller. The object is always allocated in the generic address 4567 space (address space zero).</p> 4568 4569 <h5>Arguments:</h5> 4570 <p>The '<tt>alloca</tt>' instruction 4571 allocates <tt>sizeof(<type>)*NumElements</tt> bytes of memory on the 4572 runtime stack, returning a pointer of the appropriate type to the program. 4573 If "NumElements" is specified, it is the number of elements allocated, 4574 otherwise "NumElements" is defaulted to be one. If a constant alignment is 4575 specified, the value result of the allocation is guaranteed to be aligned to 4576 at least that boundary. If not specified, or if zero, the target can choose 4577 to align the allocation on any convenient boundary compatible with the 4578 type.</p> 4579 4580 <p>'<tt>type</tt>' may be any sized type.</p> 4581 4582 <h5>Semantics:</h5> 4583 <p>Memory is allocated; a pointer is returned. The operation is undefined if 4584 there is insufficient stack space for the allocation. '<tt>alloca</tt>'d 4585 memory is automatically released when the function returns. The 4586 '<tt>alloca</tt>' instruction is commonly used to represent automatic 4587 variables that must have an address available. When the function returns 4588 (either with the <tt><a href="#i_ret">ret</a></tt> 4589 or <tt><a href="#i_unwind">unwind</a></tt> instructions), the memory is 4590 reclaimed. Allocating zero bytes is legal, but the result is undefined.</p> 4591 4592 <h5>Example:</h5> 4593 <pre> 4594 %ptr = alloca i32 <i>; yields {i32*}:ptr</i> 4595 %ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i> 4596 %ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i> 4597 %ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i> 4598 </pre> 4599 4600 </div> 4601 4602 <!-- _______________________________________________________________________ --> 4603 <h4> 4604 <a name="i_load">'<tt>load</tt>' Instruction</a> 4605 </h4> 4606 4607 <div> 4608 4609 <h5>Syntax:</h5> 4610 <pre> 4611 <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] 4612 <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> 4613 !<index> = !{ i32 1 } 4614 </pre> 4615 4616 <h5>Overview:</h5> 4617 <p>The '<tt>load</tt>' instruction is used to read from memory.</p> 4618 4619 <h5>Arguments:</h5> 4620 <p>The argument to the '<tt>load</tt>' instruction specifies the memory address 4621 from which to load. The pointer must point to 4622 a <a href="#t_firstclass">first class</a> type. If the <tt>load</tt> is 4623 marked as <tt>volatile</tt>, then the optimizer is not allowed to modify the 4624 number or order of execution of this <tt>load</tt> with other <a 4625 href="#volatile">volatile operations</a>.</p> 4626 4627 <p>If the <code>load</code> is marked as <code>atomic</code>, it takes an extra 4628 <a href="#ordering">ordering</a> and optional <code>singlethread</code> 4629 argument. The <code>release</code> and <code>acq_rel</code> orderings are 4630 not valid on <code>load</code> instructions. Atomic loads produce <a 4631 href="#memorymodel">defined</a> results when they may see multiple atomic 4632 stores. The type of the pointee must be an integer type whose bit width 4633 is a power of two greater than or equal to eight and less than or equal 4634 to a target-specific size limit. <code>align</code> must be explicitly 4635 specified on atomic loads, and the load has undefined behavior if the 4636 alignment is not set to a value which is at least the size in bytes of 4637 the pointee. <code>!nontemporal</code> does not have any defined semantics 4638 for atomic loads.</p> 4639 4640 <p>The optional constant <tt>align</tt> argument specifies the alignment of the 4641 operation (that is, the alignment of the memory address). A value of 0 or an 4642 omitted <tt>align</tt> argument means that the operation has the preferential 4643 alignment for the target. It is the responsibility of the code emitter to 4644 ensure that the alignment information is correct. Overestimating the 4645 alignment results in undefined behavior. Underestimating the alignment may 4646 produce less efficient code. An alignment of 1 is always safe.</p> 4647 4648 <p>The optional <tt>!nontemporal</tt> metadata must reference a single 4649 metatadata name <index> corresponding to a metadata node with 4650 one <tt>i32</tt> entry of value 1. The existence of 4651 the <tt>!nontemporal</tt> metatadata on the instruction tells the optimizer 4652 and code generator that this load is not expected to be reused in the cache. 4653 The code generator may select special instructions to save cache bandwidth, 4654 such as the <tt>MOVNT</tt> instruction on x86.</p> 4655 4656 <h5>Semantics:</h5> 4657 <p>The location of memory pointed to is loaded. If the value being loaded is of 4658 scalar type then the number of bytes read does not exceed the minimum number 4659 of bytes needed to hold all bits of the type. For example, loading an 4660 <tt>i24</tt> reads at most three bytes. When loading a value of a type like 4661 <tt>i20</tt> with a size that is not an integral number of bytes, the result 4662 is undefined if the value was not originally written using a store of the 4663 same type.</p> 4664 4665 <h5>Examples:</h5> 4666 <pre> 4667 %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> 4668 <a href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i> 4669 %val = load i32* %ptr <i>; yields {i32}:val = i32 3</i> 4670 </pre> 4671 4672 </div> 4673 4674 <!-- _______________________________________________________________________ --> 4675 <h4> 4676 <a name="i_store">'<tt>store</tt>' Instruction</a> 4677 </h4> 4678 4679 <div> 4680 4681 <h5>Syntax:</h5> 4682 <pre> 4683 store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] <i>; yields {void}</i> 4684 store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> <i>; yields {void}</i> 4685 </pre> 4686 4687 <h5>Overview:</h5> 4688 <p>The '<tt>store</tt>' instruction is used to write to memory.</p> 4689 4690 <h5>Arguments:</h5> 4691 <p>There are two arguments to the '<tt>store</tt>' instruction: a value to store 4692 and an address at which to store it. The type of the 4693 '<tt><pointer></tt>' operand must be a pointer to 4694 the <a href="#t_firstclass">first class</a> type of the 4695 '<tt><value></tt>' operand. If the <tt>store</tt> is marked as 4696 <tt>volatile</tt>, then the optimizer is not allowed to modify the number or 4697 order of execution of this <tt>store</tt> with other <a 4698 href="#volatile">volatile operations</a>.</p> 4699 4700 <p>If the <code>store</code> is marked as <code>atomic</code>, it takes an extra 4701 <a href="#ordering">ordering</a> and optional <code>singlethread</code> 4702 argument. The <code>acquire</code> and <code>acq_rel</code> orderings aren't 4703 valid on <code>store</code> instructions. Atomic loads produce <a 4704 href="#memorymodel">defined</a> results when they may see multiple atomic 4705 stores. The type of the pointee must be an integer type whose bit width 4706 is a power of two greater than or equal to eight and less than or equal 4707 to a target-specific size limit. <code>align</code> must be explicitly 4708 specified on atomic stores, and the store has undefined behavior if the 4709 alignment is not set to a value which is at least the size in bytes of 4710 the pointee. <code>!nontemporal</code> does not have any defined semantics 4711 for atomic stores.</p> 4712 4713 <p>The optional constant "align" argument specifies the alignment of the 4714 operation (that is, the alignment of the memory address). A value of 0 or an 4715 omitted "align" argument means that the operation has the preferential 4716 alignment for the target. It is the responsibility of the code emitter to 4717 ensure that the alignment information is correct. Overestimating the 4718 alignment results in an undefined behavior. Underestimating the alignment may 4719 produce less efficient code. An alignment of 1 is always safe.</p> 4720 4721 <p>The optional !nontemporal metadata must reference a single metatadata 4722 name <index> corresponding to a metadata node with one i32 entry of 4723 value 1. The existence of the !nontemporal metatadata on the 4724 instruction tells the optimizer and code generator that this load is 4725 not expected to be reused in the cache. The code generator may 4726 select special instructions to save cache bandwidth, such as the 4727 MOVNT instruction on x86.</p> 4728 4729 4730 <h5>Semantics:</h5> 4731 <p>The contents of memory are updated to contain '<tt><value></tt>' at the 4732 location specified by the '<tt><pointer></tt>' operand. If 4733 '<tt><value></tt>' is of scalar type then the number of bytes written 4734 does not exceed the minimum number of bytes needed to hold all bits of the 4735 type. For example, storing an <tt>i24</tt> writes at most three bytes. When 4736 writing a value of a type like <tt>i20</tt> with a size that is not an 4737 integral number of bytes, it is unspecified what happens to the extra bits 4738 that do not belong to the type, but they will typically be overwritten.</p> 4739 4740 <h5>Example:</h5> 4741 <pre> 4742 %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i> 4743 store i32 3, i32* %ptr <i>; yields {void}</i> 4744 %val = <a href="#i_load">load</a> i32* %ptr <i>; yields {i32}:val = i32 3</i> 4745 </pre> 4746 4747 </div> 4748 4749 <!-- _______________________________________________________________________ --> 4750 <h4> 4751 <a name="i_fence">'<tt>fence</tt>' Instruction</a> 4752 </h4> 4753 4754 <div> 4755 4756 <h5>Syntax:</h5> 4757 <pre> 4758 fence [singlethread] <ordering> <i>; yields {void}</i> 4759 </pre> 4760 4761 <h5>Overview:</h5> 4762 <p>The '<tt>fence</tt>' instruction is used to introduce happens-before edges 4763 between operations.</p> 4764 4765 <h5>Arguments:</h5> <p>'<code>fence</code>' instructions take an <a 4766 href="#ordering">ordering</a> argument which defines what 4767 <i>synchronizes-with</i> edges they add. They can only be given 4768 <code>acquire</code>, <code>release</code>, <code>acq_rel</code>, and 4769 <code>seq_cst</code> orderings.</p> 4770 4771 <h5>Semantics:</h5> 4772 <p>A fence <var>A</var> which has (at least) <code>release</code> ordering 4773 semantics <i>synchronizes with</i> a fence <var>B</var> with (at least) 4774 <code>acquire</code> ordering semantics if and only if there exist atomic 4775 operations <var>X</var> and <var>Y</var>, both operating on some atomic object 4776 <var>M</var>, such that <var>A</var> is sequenced before <var>X</var>, 4777 <var>X</var> modifies <var>M</var> (either directly or through some side effect 4778 of a sequence headed by <var>X</var>), <var>Y</var> is sequenced before 4779 <var>B</var>, and <var>Y</var> observes <var>M</var>. This provides a 4780 <i>happens-before</i> dependency between <var>A</var> and <var>B</var>. Rather 4781 than an explicit <code>fence</code>, one (but not both) of the atomic operations 4782 <var>X</var> or <var>Y</var> might provide a <code>release</code> or 4783 <code>acquire</code> (resp.) ordering constraint and still 4784 <i>synchronize-with</i> the explicit <code>fence</code> and establish the 4785 <i>happens-before</i> edge.</p> 4786 4787 <p>A <code>fence</code> which has <code>seq_cst</code> ordering, in addition to 4788 having both <code>acquire</code> and <code>release</code> semantics specified 4789 above, participates in the global program order of other <code>seq_cst</code> 4790 operations and/or fences.</p> 4791 4792 <p>The optional "<a href="#singlethread"><code>singlethread</code></a>" argument 4793 specifies that the fence only synchronizes with other fences in the same 4794 thread. (This is useful for interacting with signal handlers.)</p> 4795 4796 <h5>Example:</h5> 4797 <pre> 4798 fence acquire <i>; yields {void}</i> 4799 fence singlethread seq_cst <i>; yields {void}</i> 4800 </pre> 4801 4802 </div> 4803 4804 <!-- _______________________________________________________________________ --> 4805 <h4> 4806 <a name="i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a> 4807 </h4> 4808 4809 <div> 4810 4811 <h5>Syntax:</h5> 4812 <pre> 4813 cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> <i>; yields {ty}</i> 4814 </pre> 4815 4816 <h5>Overview:</h5> 4817 <p>The '<tt>cmpxchg</tt>' instruction is used to atomically modify memory. 4818 It loads a value in memory and compares it to a given value. If they are 4819 equal, it stores a new value into the memory.</p> 4820 4821 <h5>Arguments:</h5> 4822 <p>There are three arguments to the '<code>cmpxchg</code>' instruction: an 4823 address to operate on, a value to compare to the value currently be at that 4824 address, and a new value to place at that address if the compared values are 4825 equal. The type of '<var><cmp></var>' must be an integer type whose 4826 bit width is a power of two greater than or equal to eight and less than 4827 or equal to a target-specific size limit. '<var><cmp></var>' and 4828 '<var><new></var>' must have the same type, and the type of 4829 '<var><pointer></var>' must be a pointer to that type. If the 4830 <code>cmpxchg</code> is marked as <code>volatile</code>, then the 4831 optimizer is not allowed to modify the number or order of execution 4832 of this <code>cmpxchg</code> with other <a href="#volatile">volatile 4833 operations</a>.</p> 4834 4835 <!-- FIXME: Extend allowed types. --> 4836 4837 <p>The <a href="#ordering"><var>ordering</var></a> argument specifies how this 4838 <code>cmpxchg</code> synchronizes with other atomic operations.</p> 4839 4840 <p>The optional "<code>singlethread</code>" argument declares that the 4841 <code>cmpxchg</code> is only atomic with respect to code (usually signal 4842 handlers) running in the same thread as the <code>cmpxchg</code>. Otherwise the 4843 cmpxchg is atomic with respect to all other code in the system.</p> 4844 4845 <p>The pointer passed into cmpxchg must have alignment greater than or equal to 4846 the size in memory of the operand. 4847 4848 <h5>Semantics:</h5> 4849 <p>The contents of memory at the location specified by the 4850 '<tt><pointer></tt>' operand is read and compared to 4851 '<tt><cmp></tt>'; if the read value is the equal, 4852 '<tt><new></tt>' is written. The original value at the location 4853 is returned. 4854 4855 <p>A successful <code>cmpxchg</code> is a read-modify-write instruction for the 4856 purpose of identifying <a href="#release_sequence">release sequences</a>. A 4857 failed <code>cmpxchg</code> is equivalent to an atomic load with an ordering 4858 parameter determined by dropping any <code>release</code> part of the 4859 <code>cmpxchg</code>'s ordering.</p> 4860 4861 <!-- 4862 FIXME: Is compare_exchange_weak() necessary? (Consider after we've done 4863 optimization work on ARM.) 4864 4865 FIXME: Is a weaker ordering constraint on failure helpful in practice? 4866 --> 4867 4868 <h5>Example:</h5> 4869 <pre> 4870 entry: 4871 %orig = atomic <a href="#i_load">load</a> i32* %ptr unordered <i>; yields {i32}</i> 4872 <a href="#i_br">br</a> label %loop 4873 4874 loop: 4875 %cmp = <a href="#i_phi">phi</a> i32 [ %orig, %entry ], [%old, %loop] 4876 %squared = <a href="#i_mul">mul</a> i32 %cmp, %cmp 4877 %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared <i>; yields {i32}</i> 4878 %success = <a href="#i_icmp">icmp</a> eq i32 %cmp, %old 4879 <a href="#i_br">br</a> i1 %success, label %done, label %loop 4880 4881 done: 4882 ... 4883 </pre> 4884 4885 </div> 4886 4887 <!-- _______________________________________________________________________ --> 4888 <h4> 4889 <a name="i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a> 4890 </h4> 4891 4892 <div> 4893 4894 <h5>Syntax:</h5> 4895 <pre> 4896 atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> <i>; yields {ty}</i> 4897 </pre> 4898 4899 <h5>Overview:</h5> 4900 <p>The '<tt>atomicrmw</tt>' instruction is used to atomically modify memory.</p> 4901 4902 <h5>Arguments:</h5> 4903 <p>There are three arguments to the '<code>atomicrmw</code>' instruction: an 4904 operation to apply, an address whose value to modify, an argument to the 4905 operation. The operation must be one of the following keywords:</p> 4906 <ul> 4907 <li>xchg</li> 4908 <li>add</li> 4909 <li>sub</li> 4910 <li>and</li> 4911 <li>nand</li> 4912 <li>or</li> 4913 <li>xor</li> 4914 <li>max</li> 4915 <li>min</li> 4916 <li>umax</li> 4917 <li>umin</li> 4918 </ul> 4919 4920 <p>The type of '<var><value></var>' must be an integer type whose 4921 bit width is a power of two greater than or equal to eight and less than 4922 or equal to a target-specific size limit. The type of the 4923 '<code><pointer></code>' operand must be a pointer to that type. 4924 If the <code>atomicrmw</code> is marked as <code>volatile</code>, then the 4925 optimizer is not allowed to modify the number or order of execution of this 4926 <code>atomicrmw</code> with other <a href="#volatile">volatile 4927 operations</a>.</p> 4928 4929 <!-- FIXME: Extend allowed types. --> 4930 4931 <h5>Semantics:</h5> 4932 <p>The contents of memory at the location specified by the 4933 '<tt><pointer></tt>' operand are atomically read, modified, and written 4934 back. The original value at the location is returned. The modification is 4935 specified by the <var>operation</var> argument:</p> 4936 4937 <ul> 4938 <li>xchg: <code>*ptr = val</code></li> 4939 <li>add: <code>*ptr = *ptr + val</code></li> 4940 <li>sub: <code>*ptr = *ptr - val</code></li> 4941 <li>and: <code>*ptr = *ptr & val</code></li> 4942 <li>nand: <code>*ptr = ~(*ptr & val)</code></li> 4943 <li>or: <code>*ptr = *ptr | val</code></li> 4944 <li>xor: <code>*ptr = *ptr ^ val</code></li> 4945 <li>max: <code>*ptr = *ptr > val ? *ptr : val</code> (using a signed comparison)</li> 4946 <li>min: <code>*ptr = *ptr < val ? *ptr : val</code> (using a signed comparison)</li> 4947 <li>umax: <code>*ptr = *ptr > val ? *ptr : val</code> (using an unsigned comparison)</li> 4948 <li>umin: <code>*ptr = *ptr < val ? *ptr : val</code> (using an unsigned comparison)</li> 4949 </ul> 4950 4951 <h5>Example:</h5> 4952 <pre> 4953 %old = atomicrmw add i32* %ptr, i32 1 acquire <i>; yields {i32}</i> 4954 </pre> 4955 4956 </div> 4957 4958 <!-- _______________________________________________________________________ --> 4959 <h4> 4960 <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a> 4961 </h4> 4962 4963 <div> 4964 4965 <h5>Syntax:</h5> 4966 <pre> 4967 <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}* 4968 <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}* 4969 </pre> 4970 4971 <h5>Overview:</h5> 4972 <p>The '<tt>getelementptr</tt>' instruction is used to get the address of a 4973 subelement of an <a href="#t_aggregate">aggregate</a> data structure. 4974 It performs address calculation only and does not access memory.</p> 4975 4976 <h5>Arguments:</h5> 4977 <p>The first argument is always a pointer, and forms the basis of the 4978 calculation. The remaining arguments are indices that indicate which of the 4979 elements of the aggregate object are indexed. The interpretation of each 4980 index is dependent on the type being indexed into. The first index always 4981 indexes the pointer value given as the first argument, the second index 4982 indexes a value of the type pointed to (not necessarily the value directly 4983 pointed to, since the first index can be non-zero), etc. The first type 4984 indexed into must be a pointer value, subsequent types can be arrays, 4985 vectors, and structs. Note that subsequent types being indexed into 4986 can never be pointers, since that would require loading the pointer before 4987 continuing calculation.</p> 4988 4989 <p>The type of each index argument depends on the type it is indexing into. 4990 When indexing into a (optionally packed) structure, only <tt>i32</tt> 4991 integer <b>constants</b> are allowed. When indexing into an array, pointer 4992 or vector, integers of any width are allowed, and they are not required to be 4993 constant. These integers are treated as signed values where relevant.</p> 4994 4995 <p>For example, let's consider a C code fragment and how it gets compiled to 4996 LLVM:</p> 4997 4998 <pre class="doc_code"> 4999 struct RT { 5000 char A; 5001 int B[10][20]; 5002 char C; 5003 }; 5004 struct ST { 5005 int X; 5006 double Y; 5007 struct RT Z; 5008 }; 5009 5010 int *foo(struct ST *s) { 5011 return &s[1].Z.B[5][13]; 5012 } 5013 </pre> 5014 5015 <p>The LLVM code generated by the GCC frontend is:</p> 5016 5017 <pre class="doc_code"> 5018 %RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 } 5019 %ST = <a href="#namedtypes">type</a> { i32, double, %RT } 5020 5021 define i32* @foo(%ST* %s) { 5022 entry: 5023 %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13 5024 ret i32* %reg 5025 } 5026 </pre> 5027 5028 <h5>Semantics:</h5> 5029 <p>In the example above, the first index is indexing into the '<tt>%ST*</tt>' 5030 type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT 5031 }</tt>' type, a structure. The second index indexes into the third element 5032 of the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], 5033 i8 }</tt>' type, another structure. The third index indexes into the second 5034 element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an 5035 array. The two dimensions of the array are subscripted into, yielding an 5036 '<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a 5037 pointer to this element, thus computing a value of '<tt>i32*</tt>' type.</p> 5038 5039 <p>Note that it is perfectly legal to index partially through a structure, 5040 returning a pointer to an inner element. Because of this, the LLVM code for 5041 the given testcase is equivalent to:</p> 5042 5043 <pre> 5044 define i32* @foo(%ST* %s) { 5045 %t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i> 5046 %t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i> 5047 %t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i> 5048 %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i> 5049 %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i> 5050 ret i32* %t5 5051 } 5052 </pre> 5053 5054 <p>If the <tt>inbounds</tt> keyword is present, the result value of the 5055 <tt>getelementptr</tt> is a <a href="#trapvalues">trap value</a> if the 5056 base pointer is not an <i>in bounds</i> address of an allocated object, 5057 or if any of the addresses that would be formed by successive addition of 5058 the offsets implied by the indices to the base address with infinitely 5059 precise signed arithmetic are not an <i>in bounds</i> address of that 5060 allocated object. The <i>in bounds</i> addresses for an allocated object 5061 are all the addresses that point into the object, plus the address one 5062 byte past the end.</p> 5063 5064 <p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to 5065 the base address with silently-wrapping two's complement arithmetic. If the 5066 offsets have a different width from the pointer, they are sign-extended or 5067 truncated to the width of the pointer. The result value of the 5068 <tt>getelementptr</tt> may be outside the object pointed to by the base 5069 pointer. The result value may not necessarily be used to access memory 5070 though, even if it happens to point into allocated storage. See the 5071 <a href="#pointeraliasing">Pointer Aliasing Rules</a> section for more 5072 information.</p> 5073 5074 <p>The getelementptr instruction is often confusing. For some more insight into 5075 how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p> 5076 5077 <h5>Example:</h5> 5078 <pre> 5079 <i>; yields [12 x i8]*:aptr</i> 5080 %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1 5081 <i>; yields i8*:vptr</i> 5082 %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1 5083 <i>; yields i8*:eptr</i> 5084 %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1 5085 <i>; yields i32*:iptr</i> 5086 %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0 5087 </pre> 5088 5089 </div> 5090 5091 </div> 5092 5093 <!-- ======================================================================= --> 5094 <h3> 5095 <a name="convertops">Conversion Operations</a> 5096 </h3> 5097 5098 <div> 5099 5100 <p>The instructions in this category are the conversion instructions (casting) 5101 which all take a single operand and a type. They perform various bit 5102 conversions on the operand.</p> 5103 5104 <!-- _______________________________________________________________________ --> 5105 <h4> 5106 <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a> 5107 </h4> 5108 5109 <div> 5110 5111 <h5>Syntax:</h5> 5112 <pre> 5113 <result> = trunc <ty> <value> to <ty2> <i>; yields ty2</i> 5114 </pre> 5115 5116 <h5>Overview:</h5> 5117 <p>The '<tt>trunc</tt>' instruction truncates its operand to the 5118 type <tt>ty2</tt>.</p> 5119 5120 <h5>Arguments:</h5> 5121 <p>The '<tt>trunc</tt>' instruction takes a value to trunc, and a type to trunc it to. 5122 Both types must be of <a href="#t_integer">integer</a> types, or vectors 5123 of the same number of integers. 5124 The bit size of the <tt>value</tt> must be larger than 5125 the bit size of the destination type, <tt>ty2</tt>. 5126 Equal sized types are not allowed.</p> 5127 5128 <h5>Semantics:</h5> 5129 <p>The '<tt>trunc</tt>' instruction truncates the high order bits 5130 in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the 5131 source size must be larger than the destination size, <tt>trunc</tt> cannot 5132 be a <i>no-op cast</i>. It will always truncate bits.</p> 5133 5134 <h5>Example:</h5> 5135 <pre> 5136 %X = trunc i32 257 to i8 <i>; yields i8:1</i> 5137 %Y = trunc i32 123 to i1 <i>; yields i1:true</i> 5138 %Z = trunc i32 122 to i1 <i>; yields i1:false</i> 5139 %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> <i>; yields <i8 8, i8 7></i> 5140 </pre> 5141 5142 </div> 5143 5144 <!-- _______________________________________________________________________ --> 5145 <h4> 5146 <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a> 5147 </h4> 5148 5149 <div> 5150 5151 <h5>Syntax:</h5> 5152 <pre> 5153 <result> = zext <ty> <value> to <ty2> <i>; yields ty2</i> 5154 </pre> 5155 5156 <h5>Overview:</h5> 5157 <p>The '<tt>zext</tt>' instruction zero extends its operand to type 5158 <tt>ty2</tt>.</p> 5159 5160 5161 <h5>Arguments:</h5> 5162 <p>The '<tt>zext</tt>' instruction takes a value to cast, and a type to cast it to. 5163 Both types must be of <a href="#t_integer">integer</a> types, or vectors 5164 of the same number of integers. 5165 The bit size of the <tt>value</tt> must be smaller than 5166 the bit size of the destination type, 5167 <tt>ty2</tt>.</p> 5168 5169 <h5>Semantics:</h5> 5170 <p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero 5171 bits until it reaches the size of the destination type, <tt>ty2</tt>.</p> 5172 5173 <p>When zero extending from i1, the result will always be either 0 or 1.</p> 5174 5175 <h5>Example:</h5> 5176 <pre> 5177 %X = zext i32 257 to i64 <i>; yields i64:257</i> 5178 %Y = zext i1 true to i32 <i>; yields i32:1</i> 5179 %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i> 5180 </pre> 5181 5182 </div> 5183 5184 <!-- _______________________________________________________________________ --> 5185 <h4> 5186 <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a> 5187 </h4> 5188 5189 <div> 5190 5191 <h5>Syntax:</h5> 5192 <pre> 5193 <result> = sext <ty> <value> to <ty2> <i>; yields ty2</i> 5194 </pre> 5195 5196 <h5>Overview:</h5> 5197 <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p> 5198 5199 <h5>Arguments:</h5> 5200 <p>The '<tt>sext</tt>' instruction takes a value to cast, and a type to cast it to. 5201 Both types must be of <a href="#t_integer">integer</a> types, or vectors 5202 of the same number of integers. 5203 The bit size of the <tt>value</tt> must be smaller than 5204 the bit size of the destination type, 5205 <tt>ty2</tt>.</p> 5206 5207 <h5>Semantics:</h5> 5208 <p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign 5209 bit (highest order bit) of the <tt>value</tt> until it reaches the bit size 5210 of the type <tt>ty2</tt>.</p> 5211 5212 <p>When sign extending from i1, the extension always results in -1 or 0.</p> 5213 5214 <h5>Example:</h5> 5215 <pre> 5216 %X = sext i8 -1 to i16 <i>; yields i16 :65535</i> 5217 %Y = sext i1 true to i32 <i>; yields i32:-1</i> 5218 %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i> 5219 </pre> 5220 5221 </div> 5222 5223 <!-- _______________________________________________________________________ --> 5224 <h4> 5225 <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a> 5226 </h4> 5227 5228 <div> 5229 5230 <h5>Syntax:</h5> 5231 <pre> 5232 <result> = fptrunc <ty> <value> to <ty2> <i>; yields ty2</i> 5233 </pre> 5234 5235 <h5>Overview:</h5> 5236 <p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type 5237 <tt>ty2</tt>.</p> 5238 5239 <h5>Arguments:</h5> 5240 <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating 5241 point</a> value to cast and a <a href="#t_floating">floating point</a> type 5242 to cast it to. The size of <tt>value</tt> must be larger than the size of 5243 <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a 5244 <i>no-op cast</i>.</p> 5245 5246 <h5>Semantics:</h5> 5247 <p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger 5248 <a href="#t_floating">floating point</a> type to a smaller 5249 <a href="#t_floating">floating point</a> type. If the value cannot fit 5250 within the destination type, <tt>ty2</tt>, then the results are 5251 undefined.</p> 5252 5253 <h5>Example:</h5> 5254 <pre> 5255 %X = fptrunc double 123.0 to float <i>; yields float:123.0</i> 5256 %Y = fptrunc double 1.0E+300 to float <i>; yields undefined</i> 5257 </pre> 5258 5259 </div> 5260 5261 <!-- _______________________________________________________________________ --> 5262 <h4> 5263 <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a> 5264 </h4> 5265 5266 <div> 5267 5268 <h5>Syntax:</h5> 5269 <pre> 5270 <result> = fpext <ty> <value> to <ty2> <i>; yields ty2</i> 5271 </pre> 5272 5273 <h5>Overview:</h5> 5274 <p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger 5275 floating point value.</p> 5276 5277 <h5>Arguments:</h5> 5278 <p>The '<tt>fpext</tt>' instruction takes a 5279 <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and 5280 a <a href="#t_floating">floating point</a> type to cast it to. The source 5281 type must be smaller than the destination type.</p> 5282 5283 <h5>Semantics:</h5> 5284 <p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller 5285 <a href="#t_floating">floating point</a> type to a larger 5286 <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be 5287 used to make a <i>no-op cast</i> because it always changes bits. Use 5288 <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p> 5289 5290 <h5>Example:</h5> 5291 <pre> 5292 %X = fpext float 3.125 to double <i>; yields double:3.125000e+00</i> 5293 %Y = fpext double %X to fp128 <i>; yields fp128:0xL00000000000000004000900000000000</i> 5294 </pre> 5295 5296 </div> 5297 5298 <!-- _______________________________________________________________________ --> 5299 <h4> 5300 <a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a> 5301 </h4> 5302 5303 <div> 5304 5305 <h5>Syntax:</h5> 5306 <pre> 5307 <result> = fptoui <ty> <value> to <ty2> <i>; yields ty2</i> 5308 </pre> 5309 5310 <h5>Overview:</h5> 5311 <p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its 5312 unsigned integer equivalent of type <tt>ty2</tt>.</p> 5313 5314 <h5>Arguments:</h5> 5315 <p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a 5316 scalar or vector <a href="#t_floating">floating point</a> value, and a type 5317 to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> 5318 type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a 5319 vector integer type with the same number of elements as <tt>ty</tt></p> 5320 5321 <h5>Semantics:</h5> 5322 <p>The '<tt>fptoui</tt>' instruction converts its 5323 <a href="#t_floating">floating point</a> operand into the nearest (rounding 5324 towards zero) unsigned integer value. If the value cannot fit 5325 in <tt>ty2</tt>, the results are undefined.</p> 5326 5327 <h5>Example:</h5> 5328 <pre> 5329 %X = fptoui double 123.0 to i32 <i>; yields i32:123</i> 5330 %Y = fptoui float 1.0E+300 to i1 <i>; yields undefined:1</i> 5331 %Z = fptoui float 1.04E+17 to i8 <i>; yields undefined:1</i> 5332 </pre> 5333 5334 </div> 5335 5336 <!-- _______________________________________________________________________ --> 5337 <h4> 5338 <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a> 5339 </h4> 5340 5341 <div> 5342 5343 <h5>Syntax:</h5> 5344 <pre> 5345 <result> = fptosi <ty> <value> to <ty2> <i>; yields ty2</i> 5346 </pre> 5347 5348 <h5>Overview:</h5> 5349 <p>The '<tt>fptosi</tt>' instruction converts 5350 <a href="#t_floating">floating point</a> <tt>value</tt> to 5351 type <tt>ty2</tt>.</p> 5352 5353 <h5>Arguments:</h5> 5354 <p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a 5355 scalar or vector <a href="#t_floating">floating point</a> value, and a type 5356 to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> 5357 type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a 5358 vector integer type with the same number of elements as <tt>ty</tt></p> 5359 5360 <h5>Semantics:</h5> 5361 <p>The '<tt>fptosi</tt>' instruction converts its 5362 <a href="#t_floating">floating point</a> operand into the nearest (rounding 5363 towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>, 5364 the results are undefined.</p> 5365 5366 <h5>Example:</h5> 5367 <pre> 5368 %X = fptosi double -123.0 to i32 <i>; yields i32:-123</i> 5369 %Y = fptosi float 1.0E-247 to i1 <i>; yields undefined:1</i> 5370 %Z = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i> 5371 </pre> 5372 5373 </div> 5374 5375 <!-- _______________________________________________________________________ --> 5376 <h4> 5377 <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a> 5378 </h4> 5379 5380 <div> 5381 5382 <h5>Syntax:</h5> 5383 <pre> 5384 <result> = uitofp <ty> <value> to <ty2> <i>; yields ty2</i> 5385 </pre> 5386 5387 <h5>Overview:</h5> 5388 <p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned 5389 integer and converts that value to the <tt>ty2</tt> type.</p> 5390 5391 <h5>Arguments:</h5> 5392 <p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a 5393 scalar or vector <a href="#t_integer">integer</a> value, and a type to cast 5394 it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> 5395 type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector 5396 floating point type with the same number of elements as <tt>ty</tt></p> 5397 5398 <h5>Semantics:</h5> 5399 <p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned 5400 integer quantity and converts it to the corresponding floating point 5401 value. If the value cannot fit in the floating point value, the results are 5402 undefined.</p> 5403 5404 <h5>Example:</h5> 5405 <pre> 5406 %X = uitofp i32 257 to float <i>; yields float:257.0</i> 5407 %Y = uitofp i8 -1 to double <i>; yields double:255.0</i> 5408 </pre> 5409 5410 </div> 5411 5412 <!-- _______________________________________________________________________ --> 5413 <h4> 5414 <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a> 5415 </h4> 5416 5417 <div> 5418 5419 <h5>Syntax:</h5> 5420 <pre> 5421 <result> = sitofp <ty> <value> to <ty2> <i>; yields ty2</i> 5422 </pre> 5423 5424 <h5>Overview:</h5> 5425 <p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer 5426 and converts that value to the <tt>ty2</tt> type.</p> 5427 5428 <h5>Arguments:</h5> 5429 <p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a 5430 scalar or vector <a href="#t_integer">integer</a> value, and a type to cast 5431 it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a> 5432 type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector 5433 floating point type with the same number of elements as <tt>ty</tt></p> 5434 5435 <h5>Semantics:</h5> 5436 <p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer 5437 quantity and converts it to the corresponding floating point value. If the 5438 value cannot fit in the floating point value, the results are undefined.</p> 5439 5440 <h5>Example:</h5> 5441 <pre> 5442 %X = sitofp i32 257 to float <i>; yields float:257.0</i> 5443 %Y = sitofp i8 -1 to double <i>; yields double:-1.0</i> 5444 </pre> 5445 5446 </div> 5447 5448 <!-- _______________________________________________________________________ --> 5449 <h4> 5450 <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a> 5451 </h4> 5452 5453 <div> 5454 5455 <h5>Syntax:</h5> 5456 <pre> 5457 <result> = ptrtoint <ty> <value> to <ty2> <i>; yields ty2</i> 5458 </pre> 5459 5460 <h5>Overview:</h5> 5461 <p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to 5462 the integer type <tt>ty2</tt>.</p> 5463 5464 <h5>Arguments:</h5> 5465 <p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which 5466 must be a <a href="#t_pointer">pointer</a> value, and a type to cast it to 5467 <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.</p> 5468 5469 <h5>Semantics:</h5> 5470 <p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type 5471 <tt>ty2</tt> by interpreting the pointer value as an integer and either 5472 truncating or zero extending that value to the size of the integer type. If 5473 <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If 5474 <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they 5475 are the same size, then nothing is done (<i>no-op cast</i>) other than a type 5476 change.</p> 5477 5478 <h5>Example:</h5> 5479 <pre> 5480 %X = ptrtoint i32* %X to i8 <i>; yields truncation on 32-bit architecture</i> 5481 %Y = ptrtoint i32* %x to i64 <i>; yields zero extension on 32-bit architecture</i> 5482 </pre> 5483 5484 </div> 5485 5486 <!-- _______________________________________________________________________ --> 5487 <h4> 5488 <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a> 5489 </h4> 5490 5491 <div> 5492 5493 <h5>Syntax:</h5> 5494 <pre> 5495 <result> = inttoptr <ty> <value> to <ty2> <i>; yields ty2</i> 5496 </pre> 5497 5498 <h5>Overview:</h5> 5499 <p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a 5500 pointer type, <tt>ty2</tt>.</p> 5501 5502 <h5>Arguments:</h5> 5503 <p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a> 5504 value to cast, and a type to cast it to, which must be a 5505 <a href="#t_pointer">pointer</a> type.</p> 5506 5507 <h5>Semantics:</h5> 5508 <p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type 5509 <tt>ty2</tt> by applying either a zero extension or a truncation depending on 5510 the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the 5511 size of a pointer then a truncation is done. If <tt>value</tt> is smaller 5512 than the size of a pointer then a zero extension is done. If they are the 5513 same size, nothing is done (<i>no-op cast</i>).</p> 5514 5515 <h5>Example:</h5> 5516 <pre> 5517 %X = inttoptr i32 255 to i32* <i>; yields zero extension on 64-bit architecture</i> 5518 %Y = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit architecture</i> 5519 %Z = inttoptr i64 0 to i32* <i>; yields truncation on 32-bit architecture</i> 5520 </pre> 5521 5522 </div> 5523 5524 <!-- _______________________________________________________________________ --> 5525 <h4> 5526 <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a> 5527 </h4> 5528 5529 <div> 5530 5531 <h5>Syntax:</h5> 5532 <pre> 5533 <result> = bitcast <ty> <value> to <ty2> <i>; yields ty2</i> 5534 </pre> 5535 5536 <h5>Overview:</h5> 5537 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type 5538 <tt>ty2</tt> without changing any bits.</p> 5539 5540 <h5>Arguments:</h5> 5541 <p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be a 5542 non-aggregate first class value, and a type to cast it to, which must also be 5543 a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes 5544 of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be 5545 identical. If the source type is a pointer, the destination type must also be 5546 a pointer. This instruction supports bitwise conversion of vectors to 5547 integers and to vectors of other types (as long as they have the same 5548 size).</p> 5549 5550 <h5>Semantics:</h5> 5551 <p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type 5552 <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with 5553 this conversion. The conversion is done as if the <tt>value</tt> had been 5554 stored to memory and read back as type <tt>ty2</tt>. Pointer types may only 5555 be converted to other pointer types with this instruction. To convert 5556 pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or 5557 <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p> 5558 5559 <h5>Example:</h5> 5560 <pre> 5561 %X = bitcast i8 255 to i8 <i>; yields i8 :-1</i> 5562 %Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i> 5563 %Z = bitcast <2 x int> %V to i64; <i>; yields i64: %V</i> 5564 </pre> 5565 5566 </div> 5567 5568 </div> 5569 5570 <!-- ======================================================================= --> 5571 <h3> 5572 <a name="otherops">Other Operations</a> 5573 </h3> 5574 5575 <div> 5576 5577 <p>The instructions in this category are the "miscellaneous" instructions, which 5578 defy better classification.</p> 5579 5580 <!-- _______________________________________________________________________ --> 5581 <h4> 5582 <a name="i_icmp">'<tt>icmp</tt>' Instruction</a> 5583 </h4> 5584 5585 <div> 5586 5587 <h5>Syntax:</h5> 5588 <pre> 5589 <result> = icmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> 5590 </pre> 5591 5592 <h5>Overview:</h5> 5593 <p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of 5594 boolean values based on comparison of its two integer, integer vector, or 5595 pointer operands.</p> 5596 5597 <h5>Arguments:</h5> 5598 <p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is 5599 the condition code indicating the kind of comparison to perform. It is not a 5600 value, just a keyword. The possible condition code are:</p> 5601 5602 <ol> 5603 <li><tt>eq</tt>: equal</li> 5604 <li><tt>ne</tt>: not equal </li> 5605 <li><tt>ugt</tt>: unsigned greater than</li> 5606 <li><tt>uge</tt>: unsigned greater or equal</li> 5607 <li><tt>ult</tt>: unsigned less than</li> 5608 <li><tt>ule</tt>: unsigned less or equal</li> 5609 <li><tt>sgt</tt>: signed greater than</li> 5610 <li><tt>sge</tt>: signed greater or equal</li> 5611 <li><tt>slt</tt>: signed less than</li> 5612 <li><tt>sle</tt>: signed less or equal</li> 5613 </ol> 5614 5615 <p>The remaining two arguments must be <a href="#t_integer">integer</a> or 5616 <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a> 5617 typed. They must also be identical types.</p> 5618 5619 <h5>Semantics:</h5> 5620 <p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the 5621 condition code given as <tt>cond</tt>. The comparison performed always yields 5622 either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt> 5623 result, as follows:</p> 5624 5625 <ol> 5626 <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal, 5627 <tt>false</tt> otherwise. No sign interpretation is necessary or 5628 performed.</li> 5629 5630 <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal, 5631 <tt>false</tt> otherwise. No sign interpretation is necessary or 5632 performed.</li> 5633 5634 <li><tt>ugt</tt>: interprets the operands as unsigned values and yields 5635 <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> 5636 5637 <li><tt>uge</tt>: interprets the operands as unsigned values and yields 5638 <tt>true</tt> if <tt>op1</tt> is greater than or equal 5639 to <tt>op2</tt>.</li> 5640 5641 <li><tt>ult</tt>: interprets the operands as unsigned values and yields 5642 <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> 5643 5644 <li><tt>ule</tt>: interprets the operands as unsigned values and yields 5645 <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> 5646 5647 <li><tt>sgt</tt>: interprets the operands as signed values and yields 5648 <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li> 5649 5650 <li><tt>sge</tt>: interprets the operands as signed values and yields 5651 <tt>true</tt> if <tt>op1</tt> is greater than or equal 5652 to <tt>op2</tt>.</li> 5653 5654 <li><tt>slt</tt>: interprets the operands as signed values and yields 5655 <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li> 5656 5657 <li><tt>sle</tt>: interprets the operands as signed values and yields 5658 <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> 5659 </ol> 5660 5661 <p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer 5662 values are compared as if they were integers.</p> 5663 5664 <p>If the operands are integer vectors, then they are compared element by 5665 element. The result is an <tt>i1</tt> vector with the same number of elements 5666 as the values being compared. Otherwise, the result is an <tt>i1</tt>.</p> 5667 5668 <h5>Example:</h5> 5669 <pre> 5670 <result> = icmp eq i32 4, 5 <i>; yields: result=false</i> 5671 <result> = icmp ne float* %X, %X <i>; yields: result=false</i> 5672 <result> = icmp ult i16 4, 5 <i>; yields: result=true</i> 5673 <result> = icmp sgt i16 4, 5 <i>; yields: result=false</i> 5674 <result> = icmp ule i16 -4, 5 <i>; yields: result=false</i> 5675 <result> = icmp sge i16 4, 5 <i>; yields: result=false</i> 5676 </pre> 5677 5678 <p>Note that the code generator does not yet support vector types with 5679 the <tt>icmp</tt> instruction.</p> 5680 5681 </div> 5682 5683 <!-- _______________________________________________________________________ --> 5684 <h4> 5685 <a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a> 5686 </h4> 5687 5688 <div> 5689 5690 <h5>Syntax:</h5> 5691 <pre> 5692 <result> = fcmp <cond> <ty> <op1>, <op2> <i>; yields {i1} or {<N x i1>}:result</i> 5693 </pre> 5694 5695 <h5>Overview:</h5> 5696 <p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean 5697 values based on comparison of its operands.</p> 5698 5699 <p>If the operands are floating point scalars, then the result type is a boolean 5700 (<a href="#t_integer"><tt>i1</tt></a>).</p> 5701 5702 <p>If the operands are floating point vectors, then the result type is a vector 5703 of boolean with the same number of elements as the operands being 5704 compared.</p> 5705 5706 <h5>Arguments:</h5> 5707 <p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is 5708 the condition code indicating the kind of comparison to perform. It is not a 5709 value, just a keyword. The possible condition code are:</p> 5710 5711 <ol> 5712 <li><tt>false</tt>: no comparison, always returns false</li> 5713 <li><tt>oeq</tt>: ordered and equal</li> 5714 <li><tt>ogt</tt>: ordered and greater than </li> 5715 <li><tt>oge</tt>: ordered and greater than or equal</li> 5716 <li><tt>olt</tt>: ordered and less than </li> 5717 <li><tt>ole</tt>: ordered and less than or equal</li> 5718 <li><tt>one</tt>: ordered and not equal</li> 5719 <li><tt>ord</tt>: ordered (no nans)</li> 5720 <li><tt>ueq</tt>: unordered or equal</li> 5721 <li><tt>ugt</tt>: unordered or greater than </li> 5722 <li><tt>uge</tt>: unordered or greater than or equal</li> 5723 <li><tt>ult</tt>: unordered or less than </li> 5724 <li><tt>ule</tt>: unordered or less than or equal</li> 5725 <li><tt>une</tt>: unordered or not equal</li> 5726 <li><tt>uno</tt>: unordered (either nans)</li> 5727 <li><tt>true</tt>: no comparison, always returns true</li> 5728 </ol> 5729 5730 <p><i>Ordered</i> means that neither operand is a QNAN while 5731 <i>unordered</i> means that either operand may be a QNAN.</p> 5732 5733 <p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either 5734 a <a href="#t_floating">floating point</a> type or 5735 a <a href="#t_vector">vector</a> of floating point type. They must have 5736 identical types.</p> 5737 5738 <h5>Semantics:</h5> 5739 <p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt> 5740 according to the condition code given as <tt>cond</tt>. If the operands are 5741 vectors, then the vectors are compared element by element. Each comparison 5742 performed always yields an <a href="#t_integer">i1</a> result, as 5743 follows:</p> 5744 5745 <ol> 5746 <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li> 5747 5748 <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and 5749 <tt>op1</tt> is equal to <tt>op2</tt>.</li> 5750 5751 <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and 5752 <tt>op1</tt> is greater than <tt>op2</tt>.</li> 5753 5754 <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and 5755 <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> 5756 5757 <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and 5758 <tt>op1</tt> is less than <tt>op2</tt>.</li> 5759 5760 <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and 5761 <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> 5762 5763 <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and 5764 <tt>op1</tt> is not equal to <tt>op2</tt>.</li> 5765 5766 <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li> 5767 5768 <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or 5769 <tt>op1</tt> is equal to <tt>op2</tt>.</li> 5770 5771 <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or 5772 <tt>op1</tt> is greater than <tt>op2</tt>.</li> 5773 5774 <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or 5775 <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li> 5776 5777 <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or 5778 <tt>op1</tt> is less than <tt>op2</tt>.</li> 5779 5780 <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or 5781 <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li> 5782 5783 <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or 5784 <tt>op1</tt> is not equal to <tt>op2</tt>.</li> 5785 5786 <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li> 5787 5788 <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li> 5789 </ol> 5790 5791 <h5>Example:</h5> 5792 <pre> 5793 <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i> 5794 <result> = fcmp one float 4.0, 5.0 <i>; yields: result=true</i> 5795 <result> = fcmp olt float 4.0, 5.0 <i>; yields: result=true</i> 5796 <result> = fcmp ueq double 1.0, 2.0 <i>; yields: result=false</i> 5797 </pre> 5798 5799 <p>Note that the code generator does not yet support vector types with 5800 the <tt>fcmp</tt> instruction.</p> 5801 5802 </div> 5803 5804 <!-- _______________________________________________________________________ --> 5805 <h4> 5806 <a name="i_phi">'<tt>phi</tt>' Instruction</a> 5807 </h4> 5808 5809 <div> 5810 5811 <h5>Syntax:</h5> 5812 <pre> 5813 <result> = phi <ty> [ <val0>, <label0>], ... 5814 </pre> 5815 5816 <h5>Overview:</h5> 5817 <p>The '<tt>phi</tt>' instruction is used to implement the φ node in the 5818 SSA graph representing the function.</p> 5819 5820 <h5>Arguments:</h5> 5821 <p>The type of the incoming values is specified with the first type field. After 5822 this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with 5823 one pair for each predecessor basic block of the current block. Only values 5824 of <a href="#t_firstclass">first class</a> type may be used as the value 5825 arguments to the PHI node. Only labels may be used as the label 5826 arguments.</p> 5827 5828 <p>There must be no non-phi instructions between the start of a basic block and 5829 the PHI instructions: i.e. PHI instructions must be first in a basic 5830 block.</p> 5831 5832 <p>For the purposes of the SSA form, the use of each incoming value is deemed to 5833 occur on the edge from the corresponding predecessor block to the current 5834 block (but after any definition of an '<tt>invoke</tt>' instruction's return 5835 value on the same edge).</p> 5836 5837 <h5>Semantics:</h5> 5838 <p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value 5839 specified by the pair corresponding to the predecessor basic block that 5840 executed just prior to the current block.</p> 5841 5842 <h5>Example:</h5> 5843 <pre> 5844 Loop: ; Infinite loop that counts from 0 on up... 5845 %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ] 5846 %nextindvar = add i32 %indvar, 1 5847 br label %Loop 5848 </pre> 5849 5850 </div> 5851 5852 <!-- _______________________________________________________________________ --> 5853 <h4> 5854 <a name="i_select">'<tt>select</tt>' Instruction</a> 5855 </h4> 5856 5857 <div> 5858 5859 <h5>Syntax:</h5> 5860 <pre> 5861 <result> = select <i>selty</i> <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i> 5862 5863 <i>selty</i> is either i1 or {<N x i1>} 5864 </pre> 5865 5866 <h5>Overview:</h5> 5867 <p>The '<tt>select</tt>' instruction is used to choose one value based on a 5868 condition, without branching.</p> 5869 5870 5871 <h5>Arguments:</h5> 5872 <p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1' 5873 values indicating the condition, and two values of the 5874 same <a href="#t_firstclass">first class</a> type. If the val1/val2 are 5875 vectors and the condition is a scalar, then entire vectors are selected, not 5876 individual elements.</p> 5877 5878 <h5>Semantics:</h5> 5879 <p>If the condition is an i1 and it evaluates to 1, the instruction returns the 5880 first value argument; otherwise, it returns the second value argument.</p> 5881 5882 <p>If the condition is a vector of i1, then the value arguments must be vectors 5883 of the same size, and the selection is done element by element.</p> 5884 5885 <h5>Example:</h5> 5886 <pre> 5887 %X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i> 5888 </pre> 5889 5890 <p>Note that the code generator does not yet support conditions 5891 with vector type.</p> 5892 5893 </div> 5894 5895 <!-- _______________________________________________________________________ --> 5896 <h4> 5897 <a name="i_call">'<tt>call</tt>' Instruction</a> 5898 </h4> 5899 5900 <div> 5901 5902 <h5>Syntax:</h5> 5903 <pre> 5904 <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>] 5905 </pre> 5906 5907 <h5>Overview:</h5> 5908 <p>The '<tt>call</tt>' instruction represents a simple function call.</p> 5909 5910 <h5>Arguments:</h5> 5911 <p>This instruction requires several arguments:</p> 5912 5913 <ol> 5914 <li>The optional "tail" marker indicates that the callee function does not 5915 access any allocas or varargs in the caller. Note that calls may be 5916 marked "tail" even if they do not occur before 5917 a <a href="#i_ret"><tt>ret</tt></a> instruction. If the "tail" marker is 5918 present, the function call is eligible for tail call optimization, 5919 but <a href="CodeGenerator.html#tailcallopt">might not in fact be 5920 optimized into a jump</a>. The code generator may optimize calls marked 5921 "tail" with either 1) automatic <a href="CodeGenerator.html#sibcallopt"> 5922 sibling call optimization</a> when the caller and callee have 5923 matching signatures, or 2) forced tail call optimization when the 5924 following extra requirements are met: 5925 <ul> 5926 <li>Caller and callee both have the calling 5927 convention <tt>fastcc</tt>.</li> 5928 <li>The call is in tail position (ret immediately follows call and ret 5929 uses value of call or is void).</li> 5930 <li>Option <tt>-tailcallopt</tt> is enabled, 5931 or <code>llvm::GuaranteedTailCallOpt</code> is <code>true</code>.</li> 5932 <li><a href="CodeGenerator.html#tailcallopt">Platform specific 5933 constraints are met.</a></li> 5934 </ul> 5935 </li> 5936 5937 <li>The optional "cconv" marker indicates which <a href="#callingconv">calling 5938 convention</a> the call should use. If none is specified, the call 5939 defaults to using C calling conventions. The calling convention of the 5940 call must match the calling convention of the target function, or else the 5941 behavior is undefined.</li> 5942 5943 <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for 5944 return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and 5945 '<tt>inreg</tt>' attributes are valid here.</li> 5946 5947 <li>'<tt>ty</tt>': the type of the call instruction itself which is also the 5948 type of the return value. Functions that return no value are marked 5949 <tt><a href="#t_void">void</a></tt>.</li> 5950 5951 <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value 5952 being invoked. The argument types must match the types implied by this 5953 signature. This type can be omitted if the function is not varargs and if 5954 the function type does not return a pointer to a function.</li> 5955 5956 <li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to 5957 be invoked. In most cases, this is a direct function invocation, but 5958 indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer 5959 to function value.</li> 5960 5961 <li>'<tt>function args</tt>': argument list whose types match the function 5962 signature argument types and parameter attributes. All arguments must be 5963 of <a href="#t_firstclass">first class</a> type. If the function 5964 signature indicates the function accepts a variable number of arguments, 5965 the extra arguments can be specified.</li> 5966 5967 <li>The optional <a href="#fnattrs">function attributes</a> list. Only 5968 '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and 5969 '<tt>readnone</tt>' attributes are valid here.</li> 5970 </ol> 5971 5972 <h5>Semantics:</h5> 5973 <p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to 5974 a specified function, with its incoming arguments bound to the specified 5975 values. Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called 5976 function, control flow continues with the instruction after the function 5977 call, and the return value of the function is bound to the result 5978 argument.</p> 5979 5980 <h5>Example:</h5> 5981 <pre> 5982 %retval = call i32 @test(i32 %argc) 5983 call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) <i>; yields i32</i> 5984 %X = tail call i32 @foo() <i>; yields i32</i> 5985 %Y = tail call <a href="#callingconv">fastcc</a> i32 @foo() <i>; yields i32</i> 5986 call void %foo(i8 97 signext) 5987 5988 %struct.A = type { i32, i8 } 5989 %r = call %struct.A @foo() <i>; yields { 32, i8 }</i> 5990 %gr = extractvalue %struct.A %r, 0 <i>; yields i32</i> 5991 %gr1 = extractvalue %struct.A %r, 1 <i>; yields i8</i> 5992 %Z = call void @foo() noreturn <i>; indicates that %foo never returns normally</i> 5993 %ZZ = call zeroext i32 @bar() <i>; Return value is %zero extended</i> 5994 </pre> 5995 5996 <p>llvm treats calls to some functions with names and arguments that match the 5997 standard C99 library as being the C99 library functions, and may perform 5998 optimizations or generate code for them under that assumption. This is 5999 something we'd like to change in the future to provide better support for 6000 freestanding environments and non-C-based languages.</p> 6001 6002 </div> 6003 6004 <!-- _______________________________________________________________________ --> 6005 <h4> 6006 <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a> 6007 </h4> 6008 6009 <div> 6010 6011 <h5>Syntax:</h5> 6012 <pre> 6013 <resultval> = va_arg <va_list*> <arglist>, <argty> 6014 </pre> 6015 6016 <h5>Overview:</h5> 6017 <p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through 6018 the "variable argument" area of a function call. It is used to implement the 6019 <tt>va_arg</tt> macro in C.</p> 6020 6021 <h5>Arguments:</h5> 6022 <p>This instruction takes a <tt>va_list*</tt> value and the type of the 6023 argument. It returns a value of the specified argument type and increments 6024 the <tt>va_list</tt> to point to the next argument. The actual type 6025 of <tt>va_list</tt> is target specific.</p> 6026 6027 <h5>Semantics:</h5> 6028 <p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type 6029 from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point 6030 to the next argument. For more information, see the variable argument 6031 handling <a href="#int_varargs">Intrinsic Functions</a>.</p> 6032 6033 <p>It is legal for this instruction to be called in a function which does not 6034 take a variable number of arguments, for example, the <tt>vfprintf</tt> 6035 function.</p> 6036 6037 <p><tt>va_arg</tt> is an LLVM instruction instead of 6038 an <a href="#intrinsics">intrinsic function</a> because it takes a type as an 6039 argument.</p> 6040 6041 <h5>Example:</h5> 6042 <p>See the <a href="#int_varargs">variable argument processing</a> section.</p> 6043 6044 <p>Note that the code generator does not yet fully support va_arg on many 6045 targets. Also, it does not currently support va_arg with aggregate types on 6046 any target.</p> 6047 6048 </div> 6049 6050 <!-- _______________________________________________________________________ --> 6051 <h4> 6052 <a name="i_landingpad">'<tt>landingpad</tt>' Instruction</a> 6053 </h4> 6054 6055 <div> 6056 6057 <h5>Syntax:</h5> 6058 <pre> 6059 <resultval> = landingpad <somety> personality <type> <pers_fn> <clause>+ 6060 <resultval> = landingpad <somety> personality <type> <pers_fn> cleanup <clause>* 6061 6062 <clause> := catch <type> <value> 6063 <clause> := filter <array constant type> <array constant> 6064 </pre> 6065 6066 <h5>Overview:</h5> 6067 <p>The '<tt>landingpad</tt>' instruction is used by 6068 <a href="ExceptionHandling.html#overview">LLVM's exception handling 6069 system</a> to specify that a basic block is a landing pad — one where 6070 the exception lands, and corresponds to the code found in the 6071 <i><tt>catch</tt></i> portion of a <i><tt>try/catch</tt></i> sequence. It 6072 defines values supplied by the personality function (<tt>pers_fn</tt>) upon 6073 re-entry to the function. The <tt>resultval</tt> has the 6074 type <tt>somety</tt>.</p> 6075 6076 <h5>Arguments:</h5> 6077 <p>This instruction takes a <tt>pers_fn</tt> value. This is the personality 6078 function associated with the unwinding mechanism. The optional 6079 <tt>cleanup</tt> flag indicates that the landing pad block is a cleanup.</p> 6080 6081 <p>A <tt>clause</tt> begins with the clause type — <tt>catch</tt> 6082 or <tt>filter</tt> — and contains the global variable representing the 6083 "type" that may be caught or filtered respectively. Unlike the 6084 <tt>catch</tt> clause, the <tt>filter</tt> clause takes an array constant as 6085 its argument. Use "<tt>[0 x i8**] undef</tt>" for a filter which cannot 6086 throw. The '<tt>landingpad</tt>' instruction must contain <em>at least</em> 6087 one <tt>clause</tt> or the <tt>cleanup</tt> flag.</p> 6088 6089 <h5>Semantics:</h5> 6090 <p>The '<tt>landingpad</tt>' instruction defines the values which are set by the 6091 personality function (<tt>pers_fn</tt>) upon re-entry to the function, and 6092 therefore the "result type" of the <tt>landingpad</tt> instruction. As with 6093 calling conventions, how the personality function results are represented in 6094 LLVM IR is target specific.</p> 6095 6096 <p>The clauses are applied in order from top to bottom. If two 6097 <tt>landingpad</tt> instructions are merged together through inlining, the 6098 clauses from the calling function are appended to the list of clauses.</p> 6099 6100 <p>The <tt>landingpad</tt> instruction has several restrictions:</p> 6101 6102 <ul> 6103 <li>A landing pad block is a basic block which is the unwind destination of an 6104 '<tt>invoke</tt>' instruction.</li> 6105 <li>A landing pad block must have a '<tt>landingpad</tt>' instruction as its 6106 first non-PHI instruction.</li> 6107 <li>There can be only one '<tt>landingpad</tt>' instruction within the landing 6108 pad block.</li> 6109 <li>A basic block that is not a landing pad block may not include a 6110 '<tt>landingpad</tt>' instruction.</li> 6111 <li>All '<tt>landingpad</tt>' instructions in a function must have the same 6112 personality function.</li> 6113 </ul> 6114 6115 <h5>Example:</h5> 6116 <pre> 6117 ;; A landing pad which can catch an integer. 6118 %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 6119 catch i8** @_ZTIi 6120 ;; A landing pad that is a cleanup. 6121 %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 6122 cleanup 6123 ;; A landing pad which can catch an integer and can only throw a double. 6124 %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 6125 catch i8** @_ZTIi 6126 filter [1 x i8**] [@_ZTId] 6127 </pre> 6128 6129 </div> 6130 6131 </div> 6132 6133 </div> 6134 6135 <!-- *********************************************************************** --> 6136 <h2><a name="intrinsics">Intrinsic Functions</a></h2> 6137 <!-- *********************************************************************** --> 6138 6139 <div> 6140 6141 <p>LLVM supports the notion of an "intrinsic function". These functions have 6142 well known names and semantics and are required to follow certain 6143 restrictions. Overall, these intrinsics represent an extension mechanism for 6144 the LLVM language that does not require changing all of the transformations 6145 in LLVM when adding to the language (or the bitcode reader/writer, the 6146 parser, etc...).</p> 6147 6148 <p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This 6149 prefix is reserved in LLVM for intrinsic names; thus, function names may not 6150 begin with this prefix. Intrinsic functions must always be external 6151 functions: you cannot define the body of intrinsic functions. Intrinsic 6152 functions may only be used in call or invoke instructions: it is illegal to 6153 take the address of an intrinsic function. Additionally, because intrinsic 6154 functions are part of the LLVM language, it is required if any are added that 6155 they be documented here.</p> 6156 6157 <p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a 6158 family of functions that perform the same operation but on different data 6159 types. Because LLVM can represent over 8 million different integer types, 6160 overloading is used commonly to allow an intrinsic function to operate on any 6161 integer type. One or more of the argument types or the result type can be 6162 overloaded to accept any integer type. Argument types may also be defined as 6163 exactly matching a previous argument's type or the result type. This allows 6164 an intrinsic function which accepts multiple arguments, but needs all of them 6165 to be of the same type, to only be overloaded with respect to a single 6166 argument or the result.</p> 6167 6168 <p>Overloaded intrinsics will have the names of its overloaded argument types 6169 encoded into its function name, each preceded by a period. Only those types 6170 which are overloaded result in a name suffix. Arguments whose type is matched 6171 against another type do not. For example, the <tt>llvm.ctpop</tt> function 6172 can take an integer of any width and returns an integer of exactly the same 6173 integer width. This leads to a family of functions such as 6174 <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29 6175 %val)</tt>. Only one type, the return type, is overloaded, and only one type 6176 suffix is required. Because the argument's type is matched against the return 6177 type, it does not require its own name suffix.</p> 6178 6179 <p>To learn how to add an intrinsic function, please see the 6180 <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p> 6181 6182 <!-- ======================================================================= --> 6183 <h3> 6184 <a name="int_varargs">Variable Argument Handling Intrinsics</a> 6185 </h3> 6186 6187 <div> 6188 6189 <p>Variable argument support is defined in LLVM with 6190 the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three 6191 intrinsic functions. These functions are related to the similarly named 6192 macros defined in the <tt><stdarg.h></tt> header file.</p> 6193 6194 <p>All of these functions operate on arguments that use a target-specific value 6195 type "<tt>va_list</tt>". The LLVM assembly language reference manual does 6196 not define what this type is, so all transformations should be prepared to 6197 handle these functions regardless of the type used.</p> 6198 6199 <p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a> 6200 instruction and the variable argument handling intrinsic functions are 6201 used.</p> 6202 6203 <pre class="doc_code"> 6204 define i32 @test(i32 %X, ...) { 6205 ; Initialize variable argument processing 6206 %ap = alloca i8* 6207 %ap2 = bitcast i8** %ap to i8* 6208 call void @llvm.va_start(i8* %ap2) 6209 6210 ; Read a single integer argument 6211 %tmp = va_arg i8** %ap, i32 6212 6213 ; Demonstrate usage of llvm.va_copy and llvm.va_end 6214 %aq = alloca i8* 6215 %aq2 = bitcast i8** %aq to i8* 6216 call void @llvm.va_copy(i8* %aq2, i8* %ap2) 6217 call void @llvm.va_end(i8* %aq2) 6218 6219 ; Stop processing of arguments. 6220 call void @llvm.va_end(i8* %ap2) 6221 ret i32 %tmp 6222 } 6223 6224 declare void @llvm.va_start(i8*) 6225 declare void @llvm.va_copy(i8*, i8*) 6226 declare void @llvm.va_end(i8*) 6227 </pre> 6228 6229 <!-- _______________________________________________________________________ --> 6230 <h4> 6231 <a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a> 6232 </h4> 6233 6234 6235 <div> 6236 6237 <h5>Syntax:</h5> 6238 <pre> 6239 declare void %llvm.va_start(i8* <arglist>) 6240 </pre> 6241 6242 <h5>Overview:</h5> 6243 <p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*<arglist></tt> 6244 for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p> 6245 6246 <h5>Arguments:</h5> 6247 <p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p> 6248 6249 <h5>Semantics:</h5> 6250 <p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt> 6251 macro available in C. In a target-dependent way, it initializes 6252 the <tt>va_list</tt> element to which the argument points, so that the next 6253 call to <tt>va_arg</tt> will produce the first variable argument passed to 6254 the function. Unlike the C <tt>va_start</tt> macro, this intrinsic does not 6255 need to know the last argument of the function as the compiler can figure 6256 that out.</p> 6257 6258 </div> 6259 6260 <!-- _______________________________________________________________________ --> 6261 <h4> 6262 <a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a> 6263 </h4> 6264 6265 <div> 6266 6267 <h5>Syntax:</h5> 6268 <pre> 6269 declare void @llvm.va_end(i8* <arglist>) 6270 </pre> 6271 6272 <h5>Overview:</h5> 6273 <p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt>, 6274 which has been initialized previously 6275 with <tt><a href="#int_va_start">llvm.va_start</a></tt> 6276 or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p> 6277 6278 <h5>Arguments:</h5> 6279 <p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p> 6280 6281 <h5>Semantics:</h5> 6282 <p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt> 6283 macro available in C. In a target-dependent way, it destroys 6284 the <tt>va_list</tt> element to which the argument points. Calls 6285 to <a href="#int_va_start"><tt>llvm.va_start</tt></a> 6286 and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly 6287 with calls to <tt>llvm.va_end</tt>.</p> 6288 6289 </div> 6290 6291 <!-- _______________________________________________________________________ --> 6292 <h4> 6293 <a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a> 6294 </h4> 6295 6296 <div> 6297 6298 <h5>Syntax:</h5> 6299 <pre> 6300 declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>) 6301 </pre> 6302 6303 <h5>Overview:</h5> 6304 <p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position 6305 from the source argument list to the destination argument list.</p> 6306 6307 <h5>Arguments:</h5> 6308 <p>The first argument is a pointer to a <tt>va_list</tt> element to initialize. 6309 The second argument is a pointer to a <tt>va_list</tt> element to copy 6310 from.</p> 6311 6312 <h5>Semantics:</h5> 6313 <p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> 6314 macro available in C. In a target-dependent way, it copies the 6315 source <tt>va_list</tt> element into the destination <tt>va_list</tt> 6316 element. This intrinsic is necessary because 6317 the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be 6318 arbitrarily complex and require, for example, memory allocation.</p> 6319 6320 </div> 6321 6322 </div> 6323 6324 </div> 6325 6326 <!-- ======================================================================= --> 6327 <h3> 6328 <a name="int_gc">Accurate Garbage Collection Intrinsics</a> 6329 </h3> 6330 6331 <div> 6332 6333 <p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage 6334 Collection</a> (GC) requires the implementation and generation of these 6335 intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC 6336 roots on the stack</a>, as well as garbage collector implementations that 6337 require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a> 6338 barriers. Front-ends for type-safe garbage collected languages should generate 6339 these intrinsics to make use of the LLVM garbage collectors. For more details, 6340 see <a href="GarbageCollection.html">Accurate Garbage Collection with 6341 LLVM</a>.</p> 6342 6343 <p>The garbage collection intrinsics only operate on objects in the generic 6344 address space (address space zero).</p> 6345 6346 <!-- _______________________________________________________________________ --> 6347 <h4> 6348 <a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a> 6349 </h4> 6350 6351 <div> 6352 6353 <h5>Syntax:</h5> 6354 <pre> 6355 declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata) 6356 </pre> 6357 6358 <h5>Overview:</h5> 6359 <p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to 6360 the code generator, and allows some metadata to be associated with it.</p> 6361 6362 <h5>Arguments:</h5> 6363 <p>The first argument specifies the address of a stack object that contains the 6364 root pointer. The second pointer (which must be either a constant or a 6365 global value address) contains the meta-data to be associated with the 6366 root.</p> 6367 6368 <h5>Semantics:</h5> 6369 <p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc" 6370 location. At compile-time, the code generator generates information to allow 6371 the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>' 6372 intrinsic may only be used in a function which <a href="#gc">specifies a GC 6373 algorithm</a>.</p> 6374 6375 </div> 6376 6377 <!-- _______________________________________________________________________ --> 6378 <h4> 6379 <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a> 6380 </h4> 6381 6382 <div> 6383 6384 <h5>Syntax:</h5> 6385 <pre> 6386 declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr) 6387 </pre> 6388 6389 <h5>Overview:</h5> 6390 <p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap 6391 locations, allowing garbage collector implementations that require read 6392 barriers.</p> 6393 6394 <h5>Arguments:</h5> 6395 <p>The second argument is the address to read from, which should be an address 6396 allocated from the garbage collector. The first object is a pointer to the 6397 start of the referenced object, if needed by the language runtime (otherwise 6398 null).</p> 6399 6400 <h5>Semantics:</h5> 6401 <p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load 6402 instruction, but may be replaced with substantially more complex code by the 6403 garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic 6404 may only be used in a function which <a href="#gc">specifies a GC 6405 algorithm</a>.</p> 6406 6407 </div> 6408 6409 <!-- _______________________________________________________________________ --> 6410 <h4> 6411 <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a> 6412 </h4> 6413 6414 <div> 6415 6416 <h5>Syntax:</h5> 6417 <pre> 6418 declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2) 6419 </pre> 6420 6421 <h5>Overview:</h5> 6422 <p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap 6423 locations, allowing garbage collector implementations that require write 6424 barriers (such as generational or reference counting collectors).</p> 6425 6426 <h5>Arguments:</h5> 6427 <p>The first argument is the reference to store, the second is the start of the 6428 object to store it to, and the third is the address of the field of Obj to 6429 store to. If the runtime does not require a pointer to the object, Obj may 6430 be null.</p> 6431 6432 <h5>Semantics:</h5> 6433 <p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store 6434 instruction, but may be replaced with substantially more complex code by the 6435 garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic 6436 may only be used in a function which <a href="#gc">specifies a GC 6437 algorithm</a>.</p> 6438 6439 </div> 6440 6441 </div> 6442 6443 <!-- ======================================================================= --> 6444 <h3> 6445 <a name="int_codegen">Code Generator Intrinsics</a> 6446 </h3> 6447 6448 <div> 6449 6450 <p>These intrinsics are provided by LLVM to expose special features that may 6451 only be implemented with code generator support.</p> 6452 6453 <!-- _______________________________________________________________________ --> 6454 <h4> 6455 <a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a> 6456 </h4> 6457 6458 <div> 6459 6460 <h5>Syntax:</h5> 6461 <pre> 6462 declare i8 *@llvm.returnaddress(i32 <level>) 6463 </pre> 6464 6465 <h5>Overview:</h5> 6466 <p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a 6467 target-specific value indicating the return address of the current function 6468 or one of its callers.</p> 6469 6470 <h5>Arguments:</h5> 6471 <p>The argument to this intrinsic indicates which function to return the address 6472 for. Zero indicates the calling function, one indicates its caller, etc. 6473 The argument is <b>required</b> to be a constant integer value.</p> 6474 6475 <h5>Semantics:</h5> 6476 <p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer 6477 indicating the return address of the specified call frame, or zero if it 6478 cannot be identified. The value returned by this intrinsic is likely to be 6479 incorrect or 0 for arguments other than zero, so it should only be used for 6480 debugging purposes.</p> 6481 6482 <p>Note that calling this intrinsic does not prevent function inlining or other 6483 aggressive transformations, so the value returned may not be that of the 6484 obvious source-language caller.</p> 6485 6486 </div> 6487 6488 <!-- _______________________________________________________________________ --> 6489 <h4> 6490 <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a> 6491 </h4> 6492 6493 <div> 6494 6495 <h5>Syntax:</h5> 6496 <pre> 6497 declare i8* @llvm.frameaddress(i32 <level>) 6498 </pre> 6499 6500 <h5>Overview:</h5> 6501 <p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the 6502 target-specific frame pointer value for the specified stack frame.</p> 6503 6504 <h5>Arguments:</h5> 6505 <p>The argument to this intrinsic indicates which function to return the frame 6506 pointer for. Zero indicates the calling function, one indicates its caller, 6507 etc. The argument is <b>required</b> to be a constant integer value.</p> 6508 6509 <h5>Semantics:</h5> 6510 <p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer 6511 indicating the frame address of the specified call frame, or zero if it 6512 cannot be identified. The value returned by this intrinsic is likely to be 6513 incorrect or 0 for arguments other than zero, so it should only be used for 6514 debugging purposes.</p> 6515 6516 <p>Note that calling this intrinsic does not prevent function inlining or other 6517 aggressive transformations, so the value returned may not be that of the 6518 obvious source-language caller.</p> 6519 6520 </div> 6521 6522 <!-- _______________________________________________________________________ --> 6523 <h4> 6524 <a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a> 6525 </h4> 6526 6527 <div> 6528 6529 <h5>Syntax:</h5> 6530 <pre> 6531 declare i8* @llvm.stacksave() 6532 </pre> 6533 6534 <h5>Overview:</h5> 6535 <p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state 6536 of the function stack, for use 6537 with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>. This is 6538 useful for implementing language features like scoped automatic variable 6539 sized arrays in C99.</p> 6540 6541 <h5>Semantics:</h5> 6542 <p>This intrinsic returns a opaque pointer value that can be passed 6543 to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>. When 6544 an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved 6545 from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack 6546 to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed. 6547 In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the 6548 stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p> 6549 6550 </div> 6551 6552 <!-- _______________________________________________________________________ --> 6553 <h4> 6554 <a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a> 6555 </h4> 6556 6557 <div> 6558 6559 <h5>Syntax:</h5> 6560 <pre> 6561 declare void @llvm.stackrestore(i8* %ptr) 6562 </pre> 6563 6564 <h5>Overview:</h5> 6565 <p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of 6566 the function stack to the state it was in when the 6567 corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic 6568 executed. This is useful for implementing language features like scoped 6569 automatic variable sized arrays in C99.</p> 6570 6571 <h5>Semantics:</h5> 6572 <p>See the description 6573 for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p> 6574 6575 </div> 6576 6577 <!-- _______________________________________________________________________ --> 6578 <h4> 6579 <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a> 6580 </h4> 6581 6582 <div> 6583 6584 <h5>Syntax:</h5> 6585 <pre> 6586 declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>) 6587 </pre> 6588 6589 <h5>Overview:</h5> 6590 <p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to 6591 insert a prefetch instruction if supported; otherwise, it is a noop. 6592 Prefetches have no effect on the behavior of the program but can change its 6593 performance characteristics.</p> 6594 6595 <h5>Arguments:</h5> 6596 <p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the 6597 specifier determining if the fetch should be for a read (0) or write (1), 6598 and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no 6599 locality, to (3) - extremely local keep in cache. The <tt>cache type</tt> 6600 specifies whether the prefetch is performed on the data (1) or instruction (0) 6601 cache. The <tt>rw</tt>, <tt>locality</tt> and <tt>cache type</tt> arguments 6602 must be constant integers.</p> 6603 6604 <h5>Semantics:</h5> 6605 <p>This intrinsic does not modify the behavior of the program. In particular, 6606 prefetches cannot trap and do not produce a value. On targets that support 6607 this intrinsic, the prefetch can provide hints to the processor cache for 6608 better performance.</p> 6609 6610 </div> 6611 6612 <!-- _______________________________________________________________________ --> 6613 <h4> 6614 <a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a> 6615 </h4> 6616 6617 <div> 6618 6619 <h5>Syntax:</h5> 6620 <pre> 6621 declare void @llvm.pcmarker(i32 <id>) 6622 </pre> 6623 6624 <h5>Overview:</h5> 6625 <p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program 6626 Counter (PC) in a region of code to simulators and other tools. The method 6627 is target specific, but it is expected that the marker will use exported 6628 symbols to transmit the PC of the marker. The marker makes no guarantees 6629 that it will remain with any specific instruction after optimizations. It is 6630 possible that the presence of a marker will inhibit optimizations. The 6631 intended use is to be inserted after optimizations to allow correlations of 6632 simulation runs.</p> 6633 6634 <h5>Arguments:</h5> 6635 <p><tt>id</tt> is a numerical id identifying the marker.</p> 6636 6637 <h5>Semantics:</h5> 6638 <p>This intrinsic does not modify the behavior of the program. Backends that do 6639 not support this intrinsic may ignore it.</p> 6640 6641 </div> 6642 6643 <!-- _______________________________________________________________________ --> 6644 <h4> 6645 <a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a> 6646 </h4> 6647 6648 <div> 6649 6650 <h5>Syntax:</h5> 6651 <pre> 6652 declare i64 @llvm.readcyclecounter() 6653 </pre> 6654 6655 <h5>Overview:</h5> 6656 <p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle 6657 counter register (or similar low latency, high accuracy clocks) on those 6658 targets that support it. On X86, it should map to RDTSC. On Alpha, it 6659 should map to RPCC. As the backing counters overflow quickly (on the order 6660 of 9 seconds on alpha), this should only be used for small timings.</p> 6661 6662 <h5>Semantics:</h5> 6663 <p>When directly supported, reading the cycle counter should not modify any 6664 memory. Implementations are allowed to either return a application specific 6665 value or a system wide value. On backends without support, this is lowered 6666 to a constant 0.</p> 6667 6668 </div> 6669 6670 </div> 6671 6672 <!-- ======================================================================= --> 6673 <h3> 6674 <a name="int_libc">Standard C Library Intrinsics</a> 6675 </h3> 6676 6677 <div> 6678 6679 <p>LLVM provides intrinsics for a few important standard C library functions. 6680 These intrinsics allow source-language front-ends to pass information about 6681 the alignment of the pointer arguments to the code generator, providing 6682 opportunity for more efficient code generation.</p> 6683 6684 <!-- _______________________________________________________________________ --> 6685 <h4> 6686 <a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a> 6687 </h4> 6688 6689 <div> 6690 6691 <h5>Syntax:</h5> 6692 <p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any 6693 integer bit width and for different address spaces. Not all targets support 6694 all bit widths however.</p> 6695 6696 <pre> 6697 declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>, 6698 i32 <len>, i32 <align>, i1 <isvolatile>) 6699 declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>, 6700 i64 <len>, i32 <align>, i1 <isvolatile>) 6701 </pre> 6702 6703 <h5>Overview:</h5> 6704 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the 6705 source location to the destination location.</p> 6706 6707 <p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt> 6708 intrinsics do not return a value, takes extra alignment/isvolatile arguments 6709 and the pointers can be in specified address spaces.</p> 6710 6711 <h5>Arguments:</h5> 6712 6713 <p>The first argument is a pointer to the destination, the second is a pointer 6714 to the source. The third argument is an integer argument specifying the 6715 number of bytes to copy, the fourth argument is the alignment of the 6716 source and destination locations, and the fifth is a boolean indicating a 6717 volatile access.</p> 6718 6719 <p>If the call to this intrinsic has an alignment value that is not 0 or 1, 6720 then the caller guarantees that both the source and destination pointers are 6721 aligned to that boundary.</p> 6722 6723 <p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the 6724 <tt>llvm.memcpy</tt> call is a <a href="#volatile">volatile operation</a>. 6725 The detailed access behavior is not very cleanly specified and it is unwise 6726 to depend on it.</p> 6727 6728 <h5>Semantics:</h5> 6729 6730 <p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the 6731 source location to the destination location, which are not allowed to 6732 overlap. It copies "len" bytes of memory over. If the argument is known to 6733 be aligned to some boundary, this can be specified as the fourth argument, 6734 otherwise it should be set to 0 or 1.</p> 6735 6736 </div> 6737 6738 <!-- _______________________________________________________________________ --> 6739 <h4> 6740 <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a> 6741 </h4> 6742 6743 <div> 6744 6745 <h5>Syntax:</h5> 6746 <p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit 6747 width and for different address space. Not all targets support all bit 6748 widths however.</p> 6749 6750 <pre> 6751 declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>, 6752 i32 <len>, i32 <align>, i1 <isvolatile>) 6753 declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>, 6754 i64 <len>, i32 <align>, i1 <isvolatile>) 6755 </pre> 6756 6757 <h5>Overview:</h5> 6758 <p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the 6759 source location to the destination location. It is similar to the 6760 '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to 6761 overlap.</p> 6762 6763 <p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt> 6764 intrinsics do not return a value, takes extra alignment/isvolatile arguments 6765 and the pointers can be in specified address spaces.</p> 6766 6767 <h5>Arguments:</h5> 6768 6769 <p>The first argument is a pointer to the destination, the second is a pointer 6770 to the source. The third argument is an integer argument specifying the 6771 number of bytes to copy, the fourth argument is the alignment of the 6772 source and destination locations, and the fifth is a boolean indicating a 6773 volatile access.</p> 6774 6775 <p>If the call to this intrinsic has an alignment value that is not 0 or 1, 6776 then the caller guarantees that the source and destination pointers are 6777 aligned to that boundary.</p> 6778 6779 <p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the 6780 <tt>llvm.memmove</tt> call is a <a href="#volatile">volatile operation</a>. 6781 The detailed access behavior is not very cleanly specified and it is unwise 6782 to depend on it.</p> 6783 6784 <h5>Semantics:</h5> 6785 6786 <p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the 6787 source location to the destination location, which may overlap. It copies 6788 "len" bytes of memory over. If the argument is known to be aligned to some 6789 boundary, this can be specified as the fourth argument, otherwise it should 6790 be set to 0 or 1.</p> 6791 6792 </div> 6793 6794 <!-- _______________________________________________________________________ --> 6795 <h4> 6796 <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a> 6797 </h4> 6798 6799 <div> 6800 6801 <h5>Syntax:</h5> 6802 <p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit 6803 width and for different address spaces. However, not all targets support all 6804 bit widths.</p> 6805 6806 <pre> 6807 declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>, 6808 i32 <len>, i32 <align>, i1 <isvolatile>) 6809 declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>, 6810 i64 <len>, i32 <align>, i1 <isvolatile>) 6811 </pre> 6812 6813 <h5>Overview:</h5> 6814 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a 6815 particular byte value.</p> 6816 6817 <p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt> 6818 intrinsic does not return a value and takes extra alignment/volatile 6819 arguments. Also, the destination can be in an arbitrary address space.</p> 6820 6821 <h5>Arguments:</h5> 6822 <p>The first argument is a pointer to the destination to fill, the second is the 6823 byte value with which to fill it, the third argument is an integer argument 6824 specifying the number of bytes to fill, and the fourth argument is the known 6825 alignment of the destination location.</p> 6826 6827 <p>If the call to this intrinsic has an alignment value that is not 0 or 1, 6828 then the caller guarantees that the destination pointer is aligned to that 6829 boundary.</p> 6830 6831 <p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the 6832 <tt>llvm.memset</tt> call is a <a href="#volatile">volatile operation</a>. 6833 The detailed access behavior is not very cleanly specified and it is unwise 6834 to depend on it.</p> 6835 6836 <h5>Semantics:</h5> 6837 <p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting 6838 at the destination location. If the argument is known to be aligned to some 6839 boundary, this can be specified as the fourth argument, otherwise it should 6840 be set to 0 or 1.</p> 6841 6842 </div> 6843 6844 <!-- _______________________________________________________________________ --> 6845 <h4> 6846 <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a> 6847 </h4> 6848 6849 <div> 6850 6851 <h5>Syntax:</h5> 6852 <p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any 6853 floating point or vector of floating point type. Not all targets support all 6854 types however.</p> 6855 6856 <pre> 6857 declare float @llvm.sqrt.f32(float %Val) 6858 declare double @llvm.sqrt.f64(double %Val) 6859 declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val) 6860 declare fp128 @llvm.sqrt.f128(fp128 %Val) 6861 declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val) 6862 </pre> 6863 6864 <h5>Overview:</h5> 6865 <p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand, 6866 returning the same value as the libm '<tt>sqrt</tt>' functions would. 6867 Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined 6868 behavior for negative numbers other than -0.0 (which allows for better 6869 optimization, because there is no need to worry about errno being 6870 set). <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p> 6871 6872 <h5>Arguments:</h5> 6873 <p>The argument and return value are floating point numbers of the same 6874 type.</p> 6875 6876 <h5>Semantics:</h5> 6877 <p>This function returns the sqrt of the specified operand if it is a 6878 nonnegative floating point number.</p> 6879 6880 </div> 6881 6882 <!-- _______________________________________________________________________ --> 6883 <h4> 6884 <a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a> 6885 </h4> 6886 6887 <div> 6888 6889 <h5>Syntax:</h5> 6890 <p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any 6891 floating point or vector of floating point type. Not all targets support all 6892 types however.</p> 6893 6894 <pre> 6895 declare float @llvm.powi.f32(float %Val, i32 %power) 6896 declare double @llvm.powi.f64(double %Val, i32 %power) 6897 declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power) 6898 declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power) 6899 declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power) 6900 </pre> 6901 6902 <h5>Overview:</h5> 6903 <p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the 6904 specified (positive or negative) power. The order of evaluation of 6905 multiplications is not defined. When a vector of floating point type is 6906 used, the second argument remains a scalar integer value.</p> 6907 6908 <h5>Arguments:</h5> 6909 <p>The second argument is an integer power, and the first is a value to raise to 6910 that power.</p> 6911 6912 <h5>Semantics:</h5> 6913 <p>This function returns the first value raised to the second power with an 6914 unspecified sequence of rounding operations.</p> 6915 6916 </div> 6917 6918 <!-- _______________________________________________________________________ --> 6919 <h4> 6920 <a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a> 6921 </h4> 6922 6923 <div> 6924 6925 <h5>Syntax:</h5> 6926 <p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any 6927 floating point or vector of floating point type. Not all targets support all 6928 types however.</p> 6929 6930 <pre> 6931 declare float @llvm.sin.f32(float %Val) 6932 declare double @llvm.sin.f64(double %Val) 6933 declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val) 6934 declare fp128 @llvm.sin.f128(fp128 %Val) 6935 declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val) 6936 </pre> 6937 6938 <h5>Overview:</h5> 6939 <p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p> 6940 6941 <h5>Arguments:</h5> 6942 <p>The argument and return value are floating point numbers of the same 6943 type.</p> 6944 6945 <h5>Semantics:</h5> 6946 <p>This function returns the sine of the specified operand, returning the same 6947 values as the libm <tt>sin</tt> functions would, and handles error conditions 6948 in the same way.</p> 6949 6950 </div> 6951 6952 <!-- _______________________________________________________________________ --> 6953 <h4> 6954 <a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a> 6955 </h4> 6956 6957 <div> 6958 6959 <h5>Syntax:</h5> 6960 <p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any 6961 floating point or vector of floating point type. Not all targets support all 6962 types however.</p> 6963 6964 <pre> 6965 declare float @llvm.cos.f32(float %Val) 6966 declare double @llvm.cos.f64(double %Val) 6967 declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val) 6968 declare fp128 @llvm.cos.f128(fp128 %Val) 6969 declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val) 6970 </pre> 6971 6972 <h5>Overview:</h5> 6973 <p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p> 6974 6975 <h5>Arguments:</h5> 6976 <p>The argument and return value are floating point numbers of the same 6977 type.</p> 6978 6979 <h5>Semantics:</h5> 6980 <p>This function returns the cosine of the specified operand, returning the same 6981 values as the libm <tt>cos</tt> functions would, and handles error conditions 6982 in the same way.</p> 6983 6984 </div> 6985 6986 <!-- _______________________________________________________________________ --> 6987 <h4> 6988 <a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a> 6989 </h4> 6990 6991 <div> 6992 6993 <h5>Syntax:</h5> 6994 <p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any 6995 floating point or vector of floating point type. Not all targets support all 6996 types however.</p> 6997 6998 <pre> 6999 declare float @llvm.pow.f32(float %Val, float %Power) 7000 declare double @llvm.pow.f64(double %Val, double %Power) 7001 declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power) 7002 declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power) 7003 declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power) 7004 </pre> 7005 7006 <h5>Overview:</h5> 7007 <p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the 7008 specified (positive or negative) power.</p> 7009 7010 <h5>Arguments:</h5> 7011 <p>The second argument is a floating point power, and the first is a value to 7012 raise to that power.</p> 7013 7014 <h5>Semantics:</h5> 7015 <p>This function returns the first value raised to the second power, returning 7016 the same values as the libm <tt>pow</tt> functions would, and handles error 7017 conditions in the same way.</p> 7018 7019 </div> 7020 7021 </div> 7022 7023 <!-- _______________________________________________________________________ --> 7024 <h4> 7025 <a name="int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a> 7026 </h4> 7027 7028 <div> 7029 7030 <h5>Syntax:</h5> 7031 <p>This is an overloaded intrinsic. You can use <tt>llvm.exp</tt> on any 7032 floating point or vector of floating point type. Not all targets support all 7033 types however.</p> 7034 7035 <pre> 7036 declare float @llvm.exp.f32(float %Val) 7037 declare double @llvm.exp.f64(double %Val) 7038 declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val) 7039 declare fp128 @llvm.exp.f128(fp128 %Val) 7040 declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val) 7041 </pre> 7042 7043 <h5>Overview:</h5> 7044 <p>The '<tt>llvm.exp.*</tt>' intrinsics perform the exp function.</p> 7045 7046 <h5>Arguments:</h5> 7047 <p>The argument and return value are floating point numbers of the same 7048 type.</p> 7049 7050 <h5>Semantics:</h5> 7051 <p>This function returns the same values as the libm <tt>exp</tt> functions 7052 would, and handles error conditions in the same way.</p> 7053 7054 </div> 7055 7056 <!-- _______________________________________________________________________ --> 7057 <h4> 7058 <a name="int_log">'<tt>llvm.log.*</tt>' Intrinsic</a> 7059 </h4> 7060 7061 <div> 7062 7063 <h5>Syntax:</h5> 7064 <p>This is an overloaded intrinsic. You can use <tt>llvm.log</tt> on any 7065 floating point or vector of floating point type. Not all targets support all 7066 types however.</p> 7067 7068 <pre> 7069 declare float @llvm.log.f32(float %Val) 7070 declare double @llvm.log.f64(double %Val) 7071 declare x86_fp80 @llvm.log.f80(x86_fp80 %Val) 7072 declare fp128 @llvm.log.f128(fp128 %Val) 7073 declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val) 7074 </pre> 7075 7076 <h5>Overview:</h5> 7077 <p>The '<tt>llvm.log.*</tt>' intrinsics perform the log function.</p> 7078 7079 <h5>Arguments:</h5> 7080 <p>The argument and return value are floating point numbers of the same 7081 type.</p> 7082 7083 <h5>Semantics:</h5> 7084 <p>This function returns the same values as the libm <tt>log</tt> functions 7085 would, and handles error conditions in the same way.</p> 7086 7087 <h4> 7088 <a name="int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a> 7089 </h4> 7090 7091 <div> 7092 7093 <h5>Syntax:</h5> 7094 <p>This is an overloaded intrinsic. You can use <tt>llvm.fma</tt> on any 7095 floating point or vector of floating point type. Not all targets support all 7096 types however.</p> 7097 7098 <pre> 7099 declare float @llvm.fma.f32(float %a, float %b, float %c) 7100 declare double @llvm.fma.f64(double %a, double %b, double %c) 7101 declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c) 7102 declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c) 7103 declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c) 7104 </pre> 7105 7106 <h5>Overview:</h5> 7107 <p>The '<tt>llvm.fma.*</tt>' intrinsics perform the fused multiply-add 7108 operation.</p> 7109 7110 <h5>Arguments:</h5> 7111 <p>The argument and return value are floating point numbers of the same 7112 type.</p> 7113 7114 <h5>Semantics:</h5> 7115 <p>This function returns the same values as the libm <tt>fma</tt> functions 7116 would.</p> 7117 7118 </div> 7119 7120 <!-- ======================================================================= --> 7121 <h3> 7122 <a name="int_manip">Bit Manipulation Intrinsics</a> 7123 </h3> 7124 7125 <div> 7126 7127 <p>LLVM provides intrinsics for a few important bit manipulation operations. 7128 These allow efficient code generation for some algorithms.</p> 7129 7130 <!-- _______________________________________________________________________ --> 7131 <h4> 7132 <a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a> 7133 </h4> 7134 7135 <div> 7136 7137 <h5>Syntax:</h5> 7138 <p>This is an overloaded intrinsic function. You can use bswap on any integer 7139 type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p> 7140 7141 <pre> 7142 declare i16 @llvm.bswap.i16(i16 <id>) 7143 declare i32 @llvm.bswap.i32(i32 <id>) 7144 declare i64 @llvm.bswap.i64(i64 <id>) 7145 </pre> 7146 7147 <h5>Overview:</h5> 7148 <p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer 7149 values with an even number of bytes (positive multiple of 16 bits). These 7150 are useful for performing operations on data that is not in the target's 7151 native byte order.</p> 7152 7153 <h5>Semantics:</h5> 7154 <p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high 7155 and low byte of the input i16 swapped. Similarly, 7156 the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four 7157 bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1, 7158 2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order. 7159 The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics 7160 extend this concept to additional even-byte lengths (6 bytes, 8 bytes and 7161 more, respectively).</p> 7162 7163 </div> 7164 7165 <!-- _______________________________________________________________________ --> 7166 <h4> 7167 <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a> 7168 </h4> 7169 7170 <div> 7171 7172 <h5>Syntax:</h5> 7173 <p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit 7174 width, or on any vector with integer elements. Not all targets support all 7175 bit widths or vector types, however.</p> 7176 7177 <pre> 7178 declare i8 @llvm.ctpop.i8(i8 <src>) 7179 declare i16 @llvm.ctpop.i16(i16 <src>) 7180 declare i32 @llvm.ctpop.i32(i32 <src>) 7181 declare i64 @llvm.ctpop.i64(i64 <src>) 7182 declare i256 @llvm.ctpop.i256(i256 <src>) 7183 declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>) 7184 </pre> 7185 7186 <h5>Overview:</h5> 7187 <p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set 7188 in a value.</p> 7189 7190 <h5>Arguments:</h5> 7191 <p>The only argument is the value to be counted. The argument may be of any 7192 integer type, or a vector with integer elements. 7193 The return type must match the argument type.</p> 7194 7195 <h5>Semantics:</h5> 7196 <p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable, or within each 7197 element of a vector.</p> 7198 7199 </div> 7200 7201 <!-- _______________________________________________________________________ --> 7202 <h4> 7203 <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a> 7204 </h4> 7205 7206 <div> 7207 7208 <h5>Syntax:</h5> 7209 <p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any 7210 integer bit width, or any vector whose elements are integers. Not all 7211 targets support all bit widths or vector types, however.</p> 7212 7213 <pre> 7214 declare i8 @llvm.ctlz.i8 (i8 <src>) 7215 declare i16 @llvm.ctlz.i16(i16 <src>) 7216 declare i32 @llvm.ctlz.i32(i32 <src>) 7217 declare i64 @llvm.ctlz.i64(i64 <src>) 7218 declare i256 @llvm.ctlz.i256(i256 <src>) 7219 declare <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src;gt) 7220 </pre> 7221 7222 <h5>Overview:</h5> 7223 <p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of 7224 leading zeros in a variable.</p> 7225 7226 <h5>Arguments:</h5> 7227 <p>The only argument is the value to be counted. The argument may be of any 7228 integer type, or any vector type with integer element type. 7229 The return type must match the argument type.</p> 7230 7231 <h5>Semantics:</h5> 7232 <p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) 7233 zeros in a variable, or within each element of the vector if the operation 7234 is of vector type. If the src == 0 then the result is the size in bits of 7235 the type of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p> 7236 7237 </div> 7238 7239 <!-- _______________________________________________________________________ --> 7240 <h4> 7241 <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a> 7242 </h4> 7243 7244 <div> 7245 7246 <h5>Syntax:</h5> 7247 <p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any 7248 integer bit width, or any vector of integer elements. Not all targets 7249 support all bit widths or vector types, however.</p> 7250 7251 <pre> 7252 declare i8 @llvm.cttz.i8 (i8 <src>) 7253 declare i16 @llvm.cttz.i16(i16 <src>) 7254 declare i32 @llvm.cttz.i32(i32 <src>) 7255 declare i64 @llvm.cttz.i64(i64 <src>) 7256 declare i256 @llvm.cttz.i256(i256 <src>) 7257 declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>) 7258 </pre> 7259 7260 <h5>Overview:</h5> 7261 <p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of 7262 trailing zeros.</p> 7263 7264 <h5>Arguments:</h5> 7265 <p>The only argument is the value to be counted. The argument may be of any 7266 integer type, or a vectory with integer element type.. The return type 7267 must match the argument type.</p> 7268 7269 <h5>Semantics:</h5> 7270 <p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) 7271 zeros in a variable, or within each element of a vector. 7272 If the src == 0 then the result is the size in bits of 7273 the type of src. For example, <tt>llvm.cttz(2) = 1</tt>.</p> 7274 7275 </div> 7276 7277 </div> 7278 7279 <!-- ======================================================================= --> 7280 <h3> 7281 <a name="int_overflow">Arithmetic with Overflow Intrinsics</a> 7282 </h3> 7283 7284 <div> 7285 7286 <p>LLVM provides intrinsics for some arithmetic with overflow operations.</p> 7287 7288 <!-- _______________________________________________________________________ --> 7289 <h4> 7290 <a name="int_sadd_overflow"> 7291 '<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics 7292 </a> 7293 </h4> 7294 7295 <div> 7296 7297 <h5>Syntax:</h5> 7298 <p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt> 7299 on any integer bit width.</p> 7300 7301 <pre> 7302 declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) 7303 declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 7304 declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b) 7305 </pre> 7306 7307 <h5>Overview:</h5> 7308 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform 7309 a signed addition of the two arguments, and indicate whether an overflow 7310 occurred during the signed summation.</p> 7311 7312 <h5>Arguments:</h5> 7313 <p>The arguments (%a and %b) and the first element of the result structure may 7314 be of integer types of any bit width, but they must have the same bit 7315 width. The second element of the result structure must be of 7316 type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will 7317 undergo signed addition.</p> 7318 7319 <h5>Semantics:</h5> 7320 <p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform 7321 a signed addition of the two variables. They return a structure — the 7322 first element of which is the signed summation, and the second element of 7323 which is a bit specifying if the signed summation resulted in an 7324 overflow.</p> 7325 7326 <h5>Examples:</h5> 7327 <pre> 7328 %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 7329 %sum = extractvalue {i32, i1} %res, 0 7330 %obit = extractvalue {i32, i1} %res, 1 7331 br i1 %obit, label %overflow, label %normal 7332 </pre> 7333 7334 </div> 7335 7336 <!-- _______________________________________________________________________ --> 7337 <h4> 7338 <a name="int_uadd_overflow"> 7339 '<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics 7340 </a> 7341 </h4> 7342 7343 <div> 7344 7345 <h5>Syntax:</h5> 7346 <p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt> 7347 on any integer bit width.</p> 7348 7349 <pre> 7350 declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b) 7351 declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 7352 declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b) 7353 </pre> 7354 7355 <h5>Overview:</h5> 7356 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform 7357 an unsigned addition of the two arguments, and indicate whether a carry 7358 occurred during the unsigned summation.</p> 7359 7360 <h5>Arguments:</h5> 7361 <p>The arguments (%a and %b) and the first element of the result structure may 7362 be of integer types of any bit width, but they must have the same bit 7363 width. The second element of the result structure must be of 7364 type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will 7365 undergo unsigned addition.</p> 7366 7367 <h5>Semantics:</h5> 7368 <p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform 7369 an unsigned addition of the two arguments. They return a structure — 7370 the first element of which is the sum, and the second element of which is a 7371 bit specifying if the unsigned summation resulted in a carry.</p> 7372 7373 <h5>Examples:</h5> 7374 <pre> 7375 %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 7376 %sum = extractvalue {i32, i1} %res, 0 7377 %obit = extractvalue {i32, i1} %res, 1 7378 br i1 %obit, label %carry, label %normal 7379 </pre> 7380 7381 </div> 7382 7383 <!-- _______________________________________________________________________ --> 7384 <h4> 7385 <a name="int_ssub_overflow"> 7386 '<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics 7387 </a> 7388 </h4> 7389 7390 <div> 7391 7392 <h5>Syntax:</h5> 7393 <p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt> 7394 on any integer bit width.</p> 7395 7396 <pre> 7397 declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b) 7398 declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 7399 declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b) 7400 </pre> 7401 7402 <h5>Overview:</h5> 7403 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform 7404 a signed subtraction of the two arguments, and indicate whether an overflow 7405 occurred during the signed subtraction.</p> 7406 7407 <h5>Arguments:</h5> 7408 <p>The arguments (%a and %b) and the first element of the result structure may 7409 be of integer types of any bit width, but they must have the same bit 7410 width. The second element of the result structure must be of 7411 type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will 7412 undergo signed subtraction.</p> 7413 7414 <h5>Semantics:</h5> 7415 <p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform 7416 a signed subtraction of the two arguments. They return a structure — 7417 the first element of which is the subtraction, and the second element of 7418 which is a bit specifying if the signed subtraction resulted in an 7419 overflow.</p> 7420 7421 <h5>Examples:</h5> 7422 <pre> 7423 %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 7424 %sum = extractvalue {i32, i1} %res, 0 7425 %obit = extractvalue {i32, i1} %res, 1 7426 br i1 %obit, label %overflow, label %normal 7427 </pre> 7428 7429 </div> 7430 7431 <!-- _______________________________________________________________________ --> 7432 <h4> 7433 <a name="int_usub_overflow"> 7434 '<tt>llvm.usub.with.overflow.*</tt>' Intrinsics 7435 </a> 7436 </h4> 7437 7438 <div> 7439 7440 <h5>Syntax:</h5> 7441 <p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt> 7442 on any integer bit width.</p> 7443 7444 <pre> 7445 declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b) 7446 declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 7447 declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b) 7448 </pre> 7449 7450 <h5>Overview:</h5> 7451 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform 7452 an unsigned subtraction of the two arguments, and indicate whether an 7453 overflow occurred during the unsigned subtraction.</p> 7454 7455 <h5>Arguments:</h5> 7456 <p>The arguments (%a and %b) and the first element of the result structure may 7457 be of integer types of any bit width, but they must have the same bit 7458 width. The second element of the result structure must be of 7459 type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will 7460 undergo unsigned subtraction.</p> 7461 7462 <h5>Semantics:</h5> 7463 <p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform 7464 an unsigned subtraction of the two arguments. They return a structure — 7465 the first element of which is the subtraction, and the second element of 7466 which is a bit specifying if the unsigned subtraction resulted in an 7467 overflow.</p> 7468 7469 <h5>Examples:</h5> 7470 <pre> 7471 %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 7472 %sum = extractvalue {i32, i1} %res, 0 7473 %obit = extractvalue {i32, i1} %res, 1 7474 br i1 %obit, label %overflow, label %normal 7475 </pre> 7476 7477 </div> 7478 7479 <!-- _______________________________________________________________________ --> 7480 <h4> 7481 <a name="int_smul_overflow"> 7482 '<tt>llvm.smul.with.overflow.*</tt>' Intrinsics 7483 </a> 7484 </h4> 7485 7486 <div> 7487 7488 <h5>Syntax:</h5> 7489 <p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt> 7490 on any integer bit width.</p> 7491 7492 <pre> 7493 declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b) 7494 declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 7495 declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b) 7496 </pre> 7497 7498 <h5>Overview:</h5> 7499 7500 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform 7501 a signed multiplication of the two arguments, and indicate whether an 7502 overflow occurred during the signed multiplication.</p> 7503 7504 <h5>Arguments:</h5> 7505 <p>The arguments (%a and %b) and the first element of the result structure may 7506 be of integer types of any bit width, but they must have the same bit 7507 width. The second element of the result structure must be of 7508 type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will 7509 undergo signed multiplication.</p> 7510 7511 <h5>Semantics:</h5> 7512 <p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform 7513 a signed multiplication of the two arguments. They return a structure — 7514 the first element of which is the multiplication, and the second element of 7515 which is a bit specifying if the signed multiplication resulted in an 7516 overflow.</p> 7517 7518 <h5>Examples:</h5> 7519 <pre> 7520 %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 7521 %sum = extractvalue {i32, i1} %res, 0 7522 %obit = extractvalue {i32, i1} %res, 1 7523 br i1 %obit, label %overflow, label %normal 7524 </pre> 7525 7526 </div> 7527 7528 <!-- _______________________________________________________________________ --> 7529 <h4> 7530 <a name="int_umul_overflow"> 7531 '<tt>llvm.umul.with.overflow.*</tt>' Intrinsics 7532 </a> 7533 </h4> 7534 7535 <div> 7536 7537 <h5>Syntax:</h5> 7538 <p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt> 7539 on any integer bit width.</p> 7540 7541 <pre> 7542 declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b) 7543 declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 7544 declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b) 7545 </pre> 7546 7547 <h5>Overview:</h5> 7548 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform 7549 a unsigned multiplication of the two arguments, and indicate whether an 7550 overflow occurred during the unsigned multiplication.</p> 7551 7552 <h5>Arguments:</h5> 7553 <p>The arguments (%a and %b) and the first element of the result structure may 7554 be of integer types of any bit width, but they must have the same bit 7555 width. The second element of the result structure must be of 7556 type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will 7557 undergo unsigned multiplication.</p> 7558 7559 <h5>Semantics:</h5> 7560 <p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform 7561 an unsigned multiplication of the two arguments. They return a structure 7562 — the first element of which is the multiplication, and the second 7563 element of which is a bit specifying if the unsigned multiplication resulted 7564 in an overflow.</p> 7565 7566 <h5>Examples:</h5> 7567 <pre> 7568 %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 7569 %sum = extractvalue {i32, i1} %res, 0 7570 %obit = extractvalue {i32, i1} %res, 1 7571 br i1 %obit, label %overflow, label %normal 7572 </pre> 7573 7574 </div> 7575 7576 </div> 7577 7578 <!-- ======================================================================= --> 7579 <h3> 7580 <a name="int_fp16">Half Precision Floating Point Intrinsics</a> 7581 </h3> 7582 7583 <div> 7584 7585 <p>Half precision floating point is a storage-only format. This means that it is 7586 a dense encoding (in memory) but does not support computation in the 7587 format.</p> 7588 7589 <p>This means that code must first load the half-precision floating point 7590 value as an i16, then convert it to float with <a 7591 href="#int_convert_from_fp16"><tt>llvm.convert.from.fp16</tt></a>. 7592 Computation can then be performed on the float value (including extending to 7593 double etc). To store the value back to memory, it is first converted to 7594 float if needed, then converted to i16 with 7595 <a href="#int_convert_to_fp16"><tt>llvm.convert.to.fp16</tt></a>, then 7596 storing as an i16 value.</p> 7597 7598 <!-- _______________________________________________________________________ --> 7599 <h4> 7600 <a name="int_convert_to_fp16"> 7601 '<tt>llvm.convert.to.fp16</tt>' Intrinsic 7602 </a> 7603 </h4> 7604 7605 <div> 7606 7607 <h5>Syntax:</h5> 7608 <pre> 7609 declare i16 @llvm.convert.to.fp16(f32 %a) 7610 </pre> 7611 7612 <h5>Overview:</h5> 7613 <p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs 7614 a conversion from single precision floating point format to half precision 7615 floating point format.</p> 7616 7617 <h5>Arguments:</h5> 7618 <p>The intrinsic function contains single argument - the value to be 7619 converted.</p> 7620 7621 <h5>Semantics:</h5> 7622 <p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs 7623 a conversion from single precision floating point format to half precision 7624 floating point format. The return value is an <tt>i16</tt> which 7625 contains the converted number.</p> 7626 7627 <h5>Examples:</h5> 7628 <pre> 7629 %res = call i16 @llvm.convert.to.fp16(f32 %a) 7630 store i16 %res, i16* @x, align 2 7631 </pre> 7632 7633 </div> 7634 7635 <!-- _______________________________________________________________________ --> 7636 <h4> 7637 <a name="int_convert_from_fp16"> 7638 '<tt>llvm.convert.from.fp16</tt>' Intrinsic 7639 </a> 7640 </h4> 7641 7642 <div> 7643 7644 <h5>Syntax:</h5> 7645 <pre> 7646 declare f32 @llvm.convert.from.fp16(i16 %a) 7647 </pre> 7648 7649 <h5>Overview:</h5> 7650 <p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs 7651 a conversion from half precision floating point format to single precision 7652 floating point format.</p> 7653 7654 <h5>Arguments:</h5> 7655 <p>The intrinsic function contains single argument - the value to be 7656 converted.</p> 7657 7658 <h5>Semantics:</h5> 7659 <p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs a 7660 conversion from half single precision floating point format to single 7661 precision floating point format. The input half-float value is represented by 7662 an <tt>i16</tt> value.</p> 7663 7664 <h5>Examples:</h5> 7665 <pre> 7666 %a = load i16* @x, align 2 7667 %res = call f32 @llvm.convert.from.fp16(i16 %a) 7668 </pre> 7669 7670 </div> 7671 7672 </div> 7673 7674 <!-- ======================================================================= --> 7675 <h3> 7676 <a name="int_debugger">Debugger Intrinsics</a> 7677 </h3> 7678 7679 <div> 7680 7681 <p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> 7682 prefix), are described in 7683 the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source 7684 Level Debugging</a> document.</p> 7685 7686 </div> 7687 7688 <!-- ======================================================================= --> 7689 <h3> 7690 <a name="int_eh">Exception Handling Intrinsics</a> 7691 </h3> 7692 7693 <div> 7694 7695 <p>The LLVM exception handling intrinsics (which all start with 7696 <tt>llvm.eh.</tt> prefix), are described in 7697 the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception 7698 Handling</a> document.</p> 7699 7700 </div> 7701 7702 <!-- ======================================================================= --> 7703 <h3> 7704 <a name="int_trampoline">Trampoline Intrinsics</a> 7705 </h3> 7706 7707 <div> 7708 7709 <p>These intrinsics make it possible to excise one parameter, marked with 7710 the <a href="#nest"><tt>nest</tt></a> attribute, from a function. 7711 The result is a callable 7712 function pointer lacking the nest parameter - the caller does not need to 7713 provide a value for it. Instead, the value to use is stored in advance in a 7714 "trampoline", a block of memory usually allocated on the stack, which also 7715 contains code to splice the nest value into the argument list. This is used 7716 to implement the GCC nested function address extension.</p> 7717 7718 <p>For example, if the function is 7719 <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function 7720 pointer has signature <tt>i32 (i32, i32)*</tt>. It can be created as 7721 follows:</p> 7722 7723 <pre class="doc_code"> 7724 %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 7725 %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0 7726 call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval) 7727 %p = call i8* @llvm.adjust.trampoline(i8* %tramp1) 7728 %fp = bitcast i8* %p to i32 (i32, i32)* 7729 </pre> 7730 7731 <p>The call <tt>%val = call i32 %fp(i32 %x, i32 %y)</tt> is then equivalent 7732 to <tt>%val = call i32 %f(i8* %nval, i32 %x, i32 %y)</tt>.</p> 7733 7734 <!-- _______________________________________________________________________ --> 7735 <h4> 7736 <a name="int_it"> 7737 '<tt>llvm.init.trampoline</tt>' Intrinsic 7738 </a> 7739 </h4> 7740 7741 <div> 7742 7743 <h5>Syntax:</h5> 7744 <pre> 7745 declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) 7746 </pre> 7747 7748 <h5>Overview:</h5> 7749 <p>This fills the memory pointed to by <tt>tramp</tt> with executable code, 7750 turning it into a trampoline.</p> 7751 7752 <h5>Arguments:</h5> 7753 <p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all 7754 pointers. The <tt>tramp</tt> argument must point to a sufficiently large and 7755 sufficiently aligned block of memory; this memory is written to by the 7756 intrinsic. Note that the size and the alignment are target-specific - LLVM 7757 currently provides no portable way of determining them, so a front-end that 7758 generates this intrinsic needs to have some target-specific knowledge. 7759 The <tt>func</tt> argument must hold a function bitcast to 7760 an <tt>i8*</tt>.</p> 7761 7762 <h5>Semantics:</h5> 7763 <p>The block of memory pointed to by <tt>tramp</tt> is filled with target 7764 dependent code, turning it into a function. Then <tt>tramp</tt> needs to be 7765 passed to <a href="#int_at">llvm.adjust.trampoline</a> to get a pointer 7766 which can be <a href="#int_trampoline">bitcast (to a new function) and 7767 called</a>. The new function's signature is the same as that of 7768 <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute 7769 removed. At most one such <tt>nest</tt> argument is allowed, and it must be of 7770 pointer type. Calling the new function is equivalent to calling <tt>func</tt> 7771 with the same argument list, but with <tt>nval</tt> used for the missing 7772 <tt>nest</tt> argument. If, after calling <tt>llvm.init.trampoline</tt>, the 7773 memory pointed to by <tt>tramp</tt> is modified, then the effect of any later call 7774 to the returned function pointer is undefined.</p> 7775 </div> 7776 7777 <!-- _______________________________________________________________________ --> 7778 <h4> 7779 <a name="int_at"> 7780 '<tt>llvm.adjust.trampoline</tt>' Intrinsic 7781 </a> 7782 </h4> 7783 7784 <div> 7785 7786 <h5>Syntax:</h5> 7787 <pre> 7788 declare i8* @llvm.adjust.trampoline(i8* <tramp>) 7789 </pre> 7790 7791 <h5>Overview:</h5> 7792 <p>This performs any required machine-specific adjustment to the address of a 7793 trampoline (passed as <tt>tramp</tt>).</p> 7794 7795 <h5>Arguments:</h5> 7796 <p><tt>tramp</tt> must point to a block of memory which already has trampoline code 7797 filled in by a previous call to <a href="#int_it"><tt>llvm.init.trampoline</tt> 7798 </a>.</p> 7799 7800 <h5>Semantics:</h5> 7801 <p>On some architectures the address of the code to be executed needs to be 7802 different to the address where the trampoline is actually stored. This 7803 intrinsic returns the executable address corresponding to <tt>tramp</tt> 7804 after performing the required machine specific adjustments. 7805 The pointer returned can then be <a href="#int_trampoline"> bitcast and 7806 executed</a>. 7807 </p> 7808 7809 </div> 7810 7811 </div> 7812 7813 <!-- ======================================================================= --> 7814 <h3> 7815 <a name="int_atomics">Atomic Operations and Synchronization Intrinsics</a> 7816 </h3> 7817 7818 <div> 7819 7820 <p>These intrinsic functions expand the "universal IR" of LLVM to represent 7821 hardware constructs for atomic operations and memory synchronization. This 7822 provides an interface to the hardware, not an interface to the programmer. It 7823 is aimed at a low enough level to allow any programming models or APIs 7824 (Application Programming Interfaces) which need atomic behaviors to map 7825 cleanly onto it. It is also modeled primarily on hardware behavior. Just as 7826 hardware provides a "universal IR" for source languages, it also provides a 7827 starting point for developing a "universal" atomic operation and 7828 synchronization IR.</p> 7829 7830 <p>These do <em>not</em> form an API such as high-level threading libraries, 7831 software transaction memory systems, atomic primitives, and intrinsic 7832 functions as found in BSD, GNU libc, atomic_ops, APR, and other system and 7833 application libraries. The hardware interface provided by LLVM should allow 7834 a clean implementation of all of these APIs and parallel programming models. 7835 No one model or paradigm should be selected above others unless the hardware 7836 itself ubiquitously does so.</p> 7837 7838 <!-- _______________________________________________________________________ --> 7839 <h4> 7840 <a name="int_memory_barrier">'<tt>llvm.memory.barrier</tt>' Intrinsic</a> 7841 </h4> 7842 7843 <div> 7844 <h5>Syntax:</h5> 7845 <pre> 7846 declare void @llvm.memory.barrier(i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, i1 <device>) 7847 </pre> 7848 7849 <h5>Overview:</h5> 7850 <p>The <tt>llvm.memory.barrier</tt> intrinsic guarantees ordering between 7851 specific pairs of memory access types.</p> 7852 7853 <h5>Arguments:</h5> 7854 <p>The <tt>llvm.memory.barrier</tt> intrinsic requires five boolean arguments. 7855 The first four arguments enables a specific barrier as listed below. The 7856 fifth argument specifies that the barrier applies to io or device or uncached 7857 memory.</p> 7858 7859 <ul> 7860 <li><tt>ll</tt>: load-load barrier</li> 7861 <li><tt>ls</tt>: load-store barrier</li> 7862 <li><tt>sl</tt>: store-load barrier</li> 7863 <li><tt>ss</tt>: store-store barrier</li> 7864 <li><tt>device</tt>: barrier applies to device and uncached memory also.</li> 7865 </ul> 7866 7867 <h5>Semantics:</h5> 7868 <p>This intrinsic causes the system to enforce some ordering constraints upon 7869 the loads and stores of the program. This barrier does not 7870 indicate <em>when</em> any events will occur, it only enforces 7871 an <em>order</em> in which they occur. For any of the specified pairs of load 7872 and store operations (f.ex. load-load, or store-load), all of the first 7873 operations preceding the barrier will complete before any of the second 7874 operations succeeding the barrier begin. Specifically the semantics for each 7875 pairing is as follows:</p> 7876 7877 <ul> 7878 <li><tt>ll</tt>: All loads before the barrier must complete before any load 7879 after the barrier begins.</li> 7880 <li><tt>ls</tt>: All loads before the barrier must complete before any 7881 store after the barrier begins.</li> 7882 <li><tt>ss</tt>: All stores before the barrier must complete before any 7883 store after the barrier begins.</li> 7884 <li><tt>sl</tt>: All stores before the barrier must complete before any 7885 load after the barrier begins.</li> 7886 </ul> 7887 7888 <p>These semantics are applied with a logical "and" behavior when more than one 7889 is enabled in a single memory barrier intrinsic.</p> 7890 7891 <p>Backends may implement stronger barriers than those requested when they do 7892 not support as fine grained a barrier as requested. Some architectures do 7893 not need all types of barriers and on such architectures, these become 7894 noops.</p> 7895 7896 <h5>Example:</h5> 7897 <pre> 7898 %mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32)) 7899 %ptr = bitcast i8* %mallocP to i32* 7900 store i32 4, %ptr 7901 7902 %result1 = load i32* %ptr <i>; yields {i32}:result1 = 4</i> 7903 call void @llvm.memory.barrier(i1 false, i1 true, i1 false, i1 false, i1 true) 7904 <i>; guarantee the above finishes</i> 7905 store i32 8, %ptr <i>; before this begins</i> 7906 </pre> 7907 7908 </div> 7909 7910 <!-- _______________________________________________________________________ --> 7911 <h4> 7912 <a name="int_atomic_cmp_swap">'<tt>llvm.atomic.cmp.swap.*</tt>' Intrinsic</a> 7913 </h4> 7914 7915 <div> 7916 7917 <h5>Syntax:</h5> 7918 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.cmp.swap</tt> on 7919 any integer bit width and for different address spaces. Not all targets 7920 support all bit widths however.</p> 7921 7922 <pre> 7923 declare i8 @llvm.atomic.cmp.swap.i8.p0i8(i8* <ptr>, i8 <cmp>, i8 <val>) 7924 declare i16 @llvm.atomic.cmp.swap.i16.p0i16(i16* <ptr>, i16 <cmp>, i16 <val>) 7925 declare i32 @llvm.atomic.cmp.swap.i32.p0i32(i32* <ptr>, i32 <cmp>, i32 <val>) 7926 declare i64 @llvm.atomic.cmp.swap.i64.p0i64(i64* <ptr>, i64 <cmp>, i64 <val>) 7927 </pre> 7928 7929 <h5>Overview:</h5> 7930 <p>This loads a value in memory and compares it to a given value. If they are 7931 equal, it stores a new value into the memory.</p> 7932 7933 <h5>Arguments:</h5> 7934 <p>The <tt>llvm.atomic.cmp.swap</tt> intrinsic takes three arguments. The result 7935 as well as both <tt>cmp</tt> and <tt>val</tt> must be integer values with the 7936 same bit width. The <tt>ptr</tt> argument must be a pointer to a value of 7937 this integer type. While any bit width integer may be used, targets may only 7938 lower representations they support in hardware.</p> 7939 7940 <h5>Semantics:</h5> 7941 <p>This entire intrinsic must be executed atomically. It first loads the value 7942 in memory pointed to by <tt>ptr</tt> and compares it with the 7943 value <tt>cmp</tt>. If they are equal, <tt>val</tt> is stored into the 7944 memory. The loaded value is yielded in all cases. This provides the 7945 equivalent of an atomic compare-and-swap operation within the SSA 7946 framework.</p> 7947 7948 <h5>Examples:</h5> 7949 <pre> 7950 %mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32)) 7951 %ptr = bitcast i8* %mallocP to i32* 7952 store i32 4, %ptr 7953 7954 %val1 = add i32 4, 4 7955 %result1 = call i32 @llvm.atomic.cmp.swap.i32.p0i32(i32* %ptr, i32 4, %val1) 7956 <i>; yields {i32}:result1 = 4</i> 7957 %stored1 = icmp eq i32 %result1, 4 <i>; yields {i1}:stored1 = true</i> 7958 %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 8</i> 7959 7960 %val2 = add i32 1, 1 7961 %result2 = call i32 @llvm.atomic.cmp.swap.i32.p0i32(i32* %ptr, i32 5, %val2) 7962 <i>; yields {i32}:result2 = 8</i> 7963 %stored2 = icmp eq i32 %result2, 5 <i>; yields {i1}:stored2 = false</i> 7964 7965 %memval2 = load i32* %ptr <i>; yields {i32}:memval2 = 8</i> 7966 </pre> 7967 7968 </div> 7969 7970 <!-- _______________________________________________________________________ --> 7971 <h4> 7972 <a name="int_atomic_swap">'<tt>llvm.atomic.swap.*</tt>' Intrinsic</a> 7973 </h4> 7974 7975 <div> 7976 <h5>Syntax:</h5> 7977 7978 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.swap</tt> on any 7979 integer bit width. Not all targets support all bit widths however.</p> 7980 7981 <pre> 7982 declare i8 @llvm.atomic.swap.i8.p0i8(i8* <ptr>, i8 <val>) 7983 declare i16 @llvm.atomic.swap.i16.p0i16(i16* <ptr>, i16 <val>) 7984 declare i32 @llvm.atomic.swap.i32.p0i32(i32* <ptr>, i32 <val>) 7985 declare i64 @llvm.atomic.swap.i64.p0i64(i64* <ptr>, i64 <val>) 7986 </pre> 7987 7988 <h5>Overview:</h5> 7989 <p>This intrinsic loads the value stored in memory at <tt>ptr</tt> and yields 7990 the value from memory. It then stores the value in <tt>val</tt> in the memory 7991 at <tt>ptr</tt>.</p> 7992 7993 <h5>Arguments:</h5> 7994 <p>The <tt>llvm.atomic.swap</tt> intrinsic takes two arguments. Both 7995 the <tt>val</tt> argument and the result must be integers of the same bit 7996 width. The first argument, <tt>ptr</tt>, must be a pointer to a value of this 7997 integer type. The targets may only lower integer representations they 7998 support.</p> 7999 8000 <h5>Semantics:</h5> 8001 <p>This intrinsic loads the value pointed to by <tt>ptr</tt>, yields it, and 8002 stores <tt>val</tt> back into <tt>ptr</tt> atomically. This provides the 8003 equivalent of an atomic swap operation within the SSA framework.</p> 8004 8005 <h5>Examples:</h5> 8006 <pre> 8007 %mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32)) 8008 %ptr = bitcast i8* %mallocP to i32* 8009 store i32 4, %ptr 8010 8011 %val1 = add i32 4, 4 8012 %result1 = call i32 @llvm.atomic.swap.i32.p0i32(i32* %ptr, i32 %val1) 8013 <i>; yields {i32}:result1 = 4</i> 8014 %stored1 = icmp eq i32 %result1, 4 <i>; yields {i1}:stored1 = true</i> 8015 %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 8</i> 8016 8017 %val2 = add i32 1, 1 8018 %result2 = call i32 @llvm.atomic.swap.i32.p0i32(i32* %ptr, i32 %val2) 8019 <i>; yields {i32}:result2 = 8</i> 8020 8021 %stored2 = icmp eq i32 %result2, 8 <i>; yields {i1}:stored2 = true</i> 8022 %memval2 = load i32* %ptr <i>; yields {i32}:memval2 = 2</i> 8023 </pre> 8024 8025 </div> 8026 8027 <!-- _______________________________________________________________________ --> 8028 <h4> 8029 <a name="int_atomic_load_add">'<tt>llvm.atomic.load.add.*</tt>' Intrinsic</a> 8030 </h4> 8031 8032 <div> 8033 8034 <h5>Syntax:</h5> 8035 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.add</tt> on 8036 any integer bit width. Not all targets support all bit widths however.</p> 8037 8038 <pre> 8039 declare i8 @llvm.atomic.load.add.i8.p0i8(i8* <ptr>, i8 <delta>) 8040 declare i16 @llvm.atomic.load.add.i16.p0i16(i16* <ptr>, i16 <delta>) 8041 declare i32 @llvm.atomic.load.add.i32.p0i32(i32* <ptr>, i32 <delta>) 8042 declare i64 @llvm.atomic.load.add.i64.p0i64(i64* <ptr>, i64 <delta>) 8043 </pre> 8044 8045 <h5>Overview:</h5> 8046 <p>This intrinsic adds <tt>delta</tt> to the value stored in memory 8047 at <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p> 8048 8049 <h5>Arguments:</h5> 8050 <p>The intrinsic takes two arguments, the first a pointer to an integer value 8051 and the second an integer value. The result is also an integer value. These 8052 integer types can have any bit width, but they must all have the same bit 8053 width. The targets may only lower integer representations they support.</p> 8054 8055 <h5>Semantics:</h5> 8056 <p>This intrinsic does a series of operations atomically. It first loads the 8057 value stored at <tt>ptr</tt>. It then adds <tt>delta</tt>, stores the result 8058 to <tt>ptr</tt>. It yields the original value stored at <tt>ptr</tt>.</p> 8059 8060 <h5>Examples:</h5> 8061 <pre> 8062 %mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32)) 8063 %ptr = bitcast i8* %mallocP to i32* 8064 store i32 4, %ptr 8065 %result1 = call i32 @llvm.atomic.load.add.i32.p0i32(i32* %ptr, i32 4) 8066 <i>; yields {i32}:result1 = 4</i> 8067 %result2 = call i32 @llvm.atomic.load.add.i32.p0i32(i32* %ptr, i32 2) 8068 <i>; yields {i32}:result2 = 8</i> 8069 %result3 = call i32 @llvm.atomic.load.add.i32.p0i32(i32* %ptr, i32 5) 8070 <i>; yields {i32}:result3 = 10</i> 8071 %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 15</i> 8072 </pre> 8073 8074 </div> 8075 8076 <!-- _______________________________________________________________________ --> 8077 <h4> 8078 <a name="int_atomic_load_sub">'<tt>llvm.atomic.load.sub.*</tt>' Intrinsic</a> 8079 </h4> 8080 8081 <div> 8082 8083 <h5>Syntax:</h5> 8084 <p>This is an overloaded intrinsic. You can use <tt>llvm.atomic.load.sub</tt> on 8085 any integer bit width and for different address spaces. Not all targets 8086 support all bit widths however.</p> 8087 8088 <pre> 8089 declare i8 @llvm.atomic.load.sub.i8.p0i32(i8* <ptr>, i8 <delta>) 8090 declare i16 @llvm.atomic.load.sub.i16.p0i32(i16* <ptr>, i16 <delta>) 8091 declare i32 @llvm.atomic.load.sub.i32.p0i32(i32* <ptr>, i32 <delta>) 8092 declare i64 @llvm.atomic.load.sub.i64.p0i32(i64* <ptr>, i64 <delta>) 8093 </pre> 8094 8095 <h5>Overview:</h5> 8096 <p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at 8097 <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p> 8098 8099 <h5>Arguments:</h5> 8100 <p>The intrinsic takes two arguments, the first a pointer to an integer value 8101 and the second an integer value. The result is also an integer value. These 8102 integer types can have any bit width, but they must all have the same bit 8103 width. The targets may only lower integer representations they support.</p> 8104 8105 <h5>Semantics:</h5> 8106 <p>This intrinsic does a series of operations atomically. It first loads the 8107 value stored at <tt>ptr</tt>. It then subtracts <tt>delta</tt>, stores the 8108 result to <tt>ptr</tt>. It yields the original value stored 8109 at <tt>ptr</tt>.</p> 8110 8111 <h5>Examples:</h5> 8112 <pre> 8113 %mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32)) 8114 %ptr = bitcast i8* %mallocP to i32* 8115 store i32 8, %ptr 8116 %result1 = call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %ptr, i32 4) 8117 <i>; yields {i32}:result1 = 8</i> 8118 %result2 = call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %ptr, i32 2) 8119 <i>; yields {i32}:result2 = 4</i> 8120 %result3 = call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %ptr, i32 5) 8121 <i>; yields {i32}:result3 = 2</i> 8122 %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = -3</i> 8123 </pre> 8124 8125 </div> 8126 8127 <!-- _______________________________________________________________________ --> 8128 <h4> 8129 <a name="int_atomic_load_and"> 8130 '<tt>llvm.atomic.load.and.*</tt>' Intrinsic 8131 </a> 8132 <br> 8133 <a name="int_atomic_load_nand"> 8134 '<tt>llvm.atomic.load.nand.*</tt>' Intrinsic 8135 </a> 8136 <br> 8137 <a name="int_atomic_load_or"> 8138 '<tt>llvm.atomic.load.or.*</tt>' Intrinsic 8139 </a> 8140 <br> 8141 <a name="int_atomic_load_xor"> 8142 '<tt>llvm.atomic.load.xor.*</tt>' Intrinsic 8143 </a> 8144 </h4> 8145 8146 <div> 8147 8148 <h5>Syntax:</h5> 8149 <p>These are overloaded intrinsics. You can 8150 use <tt>llvm.atomic.load_and</tt>, <tt>llvm.atomic.load_nand</tt>, 8151 <tt>llvm.atomic.load_or</tt>, and <tt>llvm.atomic.load_xor</tt> on any integer 8152 bit width and for different address spaces. Not all targets support all bit 8153 widths however.</p> 8154 8155 <pre> 8156 declare i8 @llvm.atomic.load.and.i8.p0i8(i8* <ptr>, i8 <delta>) 8157 declare i16 @llvm.atomic.load.and.i16.p0i16(i16* <ptr>, i16 <delta>) 8158 declare i32 @llvm.atomic.load.and.i32.p0i32(i32* <ptr>, i32 <delta>) 8159 declare i64 @llvm.atomic.load.and.i64.p0i64(i64* <ptr>, i64 <delta>) 8160 </pre> 8161 8162 <pre> 8163 declare i8 @llvm.atomic.load.or.i8.p0i8(i8* <ptr>, i8 <delta>) 8164 declare i16 @llvm.atomic.load.or.i16.p0i16(i16* <ptr>, i16 <delta>) 8165 declare i32 @llvm.atomic.load.or.i32.p0i32(i32* <ptr>, i32 <delta>) 8166 declare i64 @llvm.atomic.load.or.i64.p0i64(i64* <ptr>, i64 <delta>) 8167 </pre> 8168 8169 <pre> 8170 declare i8 @llvm.atomic.load.nand.i8.p0i32(i8* <ptr>, i8 <delta>) 8171 declare i16 @llvm.atomic.load.nand.i16.p0i32(i16* <ptr>, i16 <delta>) 8172 declare i32 @llvm.atomic.load.nand.i32.p0i32(i32* <ptr>, i32 <delta>) 8173 declare i64 @llvm.atomic.load.nand.i64.p0i32(i64* <ptr>, i64 <delta>) 8174 </pre> 8175 8176 <pre> 8177 declare i8 @llvm.atomic.load.xor.i8.p0i32(i8* <ptr>, i8 <delta>) 8178 declare i16 @llvm.atomic.load.xor.i16.p0i32(i16* <ptr>, i16 <delta>) 8179 declare i32 @llvm.atomic.load.xor.i32.p0i32(i32* <ptr>, i32 <delta>) 8180 declare i64 @llvm.atomic.load.xor.i64.p0i32(i64* <ptr>, i64 <delta>) 8181 </pre> 8182 8183 <h5>Overview:</h5> 8184 <p>These intrinsics bitwise the operation (and, nand, or, xor) <tt>delta</tt> to 8185 the value stored in memory at <tt>ptr</tt>. It yields the original value 8186 at <tt>ptr</tt>.</p> 8187 8188 <h5>Arguments:</h5> 8189 <p>These intrinsics take two arguments, the first a pointer to an integer value 8190 and the second an integer value. The result is also an integer value. These 8191 integer types can have any bit width, but they must all have the same bit 8192 width. The targets may only lower integer representations they support.</p> 8193 8194 <h5>Semantics:</h5> 8195 <p>These intrinsics does a series of operations atomically. They first load the 8196 value stored at <tt>ptr</tt>. They then do the bitwise 8197 operation <tt>delta</tt>, store the result to <tt>ptr</tt>. They yield the 8198 original value stored at <tt>ptr</tt>.</p> 8199 8200 <h5>Examples:</h5> 8201 <pre> 8202 %mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32)) 8203 %ptr = bitcast i8* %mallocP to i32* 8204 store i32 0x0F0F, %ptr 8205 %result0 = call i32 @llvm.atomic.load.nand.i32.p0i32(i32* %ptr, i32 0xFF) 8206 <i>; yields {i32}:result0 = 0x0F0F</i> 8207 %result1 = call i32 @llvm.atomic.load.and.i32.p0i32(i32* %ptr, i32 0xFF) 8208 <i>; yields {i32}:result1 = 0xFFFFFFF0</i> 8209 %result2 = call i32 @llvm.atomic.load.or.i32.p0i32(i32* %ptr, i32 0F) 8210 <i>; yields {i32}:result2 = 0xF0</i> 8211 %result3 = call i32 @llvm.atomic.load.xor.i32.p0i32(i32* %ptr, i32 0F) 8212 <i>; yields {i32}:result3 = FF</i> 8213 %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = F0</i> 8214 </pre> 8215 8216 </div> 8217 8218 <!-- _______________________________________________________________________ --> 8219 <h4> 8220 <a name="int_atomic_load_max"> 8221 '<tt>llvm.atomic.load.max.*</tt>' Intrinsic 8222 </a> 8223 <br> 8224 <a name="int_atomic_load_min"> 8225 '<tt>llvm.atomic.load.min.*</tt>' Intrinsic 8226 </a> 8227 <br> 8228 <a name="int_atomic_load_umax"> 8229 '<tt>llvm.atomic.load.umax.*</tt>' Intrinsic 8230 </a> 8231 <br> 8232 <a name="int_atomic_load_umin"> 8233 '<tt>llvm.atomic.load.umin.*</tt>' Intrinsic 8234 </a> 8235 </h4> 8236 8237 <div> 8238 8239 <h5>Syntax:</h5> 8240 <p>These are overloaded intrinsics. You can use <tt>llvm.atomic.load_max</tt>, 8241 <tt>llvm.atomic.load_min</tt>, <tt>llvm.atomic.load_umax</tt>, and 8242 <tt>llvm.atomic.load_umin</tt> on any integer bit width and for different 8243 address spaces. Not all targets support all bit widths however.</p> 8244 8245 <pre> 8246 declare i8 @llvm.atomic.load.max.i8.p0i8(i8* <ptr>, i8 <delta>) 8247 declare i16 @llvm.atomic.load.max.i16.p0i16(i16* <ptr>, i16 <delta>) 8248 declare i32 @llvm.atomic.load.max.i32.p0i32(i32* <ptr>, i32 <delta>) 8249 declare i64 @llvm.atomic.load.max.i64.p0i64(i64* <ptr>, i64 <delta>) 8250 </pre> 8251 8252 <pre> 8253 declare i8 @llvm.atomic.load.min.i8.p0i8(i8* <ptr>, i8 <delta>) 8254 declare i16 @llvm.atomic.load.min.i16.p0i16(i16* <ptr>, i16 <delta>) 8255 declare i32 @llvm.atomic.load.min.i32.p0i32(i32* <ptr>, i32 <delta>) 8256 declare i64 @llvm.atomic.load.min.i64.p0i64(i64* <ptr>, i64 <delta>) 8257 </pre> 8258 8259 <pre> 8260 declare i8 @llvm.atomic.load.umax.i8.p0i8(i8* <ptr>, i8 <delta>) 8261 declare i16 @llvm.atomic.load.umax.i16.p0i16(i16* <ptr>, i16 <delta>) 8262 declare i32 @llvm.atomic.load.umax.i32.p0i32(i32* <ptr>, i32 <delta>) 8263 declare i64 @llvm.atomic.load.umax.i64.p0i64(i64* <ptr>, i64 <delta>) 8264 </pre> 8265 8266 <pre> 8267 declare i8 @llvm.atomic.load.umin.i8.p0i8(i8* <ptr>, i8 <delta>) 8268 declare i16 @llvm.atomic.load.umin.i16.p0i16(i16* <ptr>, i16 <delta>) 8269 declare i32 @llvm.atomic.load.umin.i32.p0i32(i32* <ptr>, i32 <delta>) 8270 declare i64 @llvm.atomic.load.umin.i64.p0i64(i64* <ptr>, i64 <delta>) 8271 </pre> 8272 8273 <h5>Overview:</h5> 8274 <p>These intrinsics takes the signed or unsigned minimum or maximum of 8275 <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the 8276 original value at <tt>ptr</tt>.</p> 8277 8278 <h5>Arguments:</h5> 8279 <p>These intrinsics take two arguments, the first a pointer to an integer value 8280 and the second an integer value. The result is also an integer value. These 8281 integer types can have any bit width, but they must all have the same bit 8282 width. The targets may only lower integer representations they support.</p> 8283 8284 <h5>Semantics:</h5> 8285 <p>These intrinsics does a series of operations atomically. They first load the 8286 value stored at <tt>ptr</tt>. They then do the signed or unsigned min or 8287 max <tt>delta</tt> and the value, store the result to <tt>ptr</tt>. They 8288 yield the original value stored at <tt>ptr</tt>.</p> 8289 8290 <h5>Examples:</h5> 8291 <pre> 8292 %mallocP = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32)) 8293 %ptr = bitcast i8* %mallocP to i32* 8294 store i32 7, %ptr 8295 %result0 = call i32 @llvm.atomic.load.min.i32.p0i32(i32* %ptr, i32 -2) 8296 <i>; yields {i32}:result0 = 7</i> 8297 %result1 = call i32 @llvm.atomic.load.max.i32.p0i32(i32* %ptr, i32 8) 8298 <i>; yields {i32}:result1 = -2</i> 8299 %result2 = call i32 @llvm.atomic.load.umin.i32.p0i32(i32* %ptr, i32 10) 8300 <i>; yields {i32}:result2 = 8</i> 8301 %result3 = call i32 @llvm.atomic.load.umax.i32.p0i32(i32* %ptr, i32 30) 8302 <i>; yields {i32}:result3 = 8</i> 8303 %memval1 = load i32* %ptr <i>; yields {i32}:memval1 = 30</i> 8304 </pre> 8305 8306 </div> 8307 8308 </div> 8309 8310 <!-- ======================================================================= --> 8311 <h3> 8312 <a name="int_memorymarkers">Memory Use Markers</a> 8313 </h3> 8314 8315 <div> 8316 8317 <p>This class of intrinsics exists to information about the lifetime of memory 8318 objects and ranges where variables are immutable.</p> 8319 8320 <!-- _______________________________________________________________________ --> 8321 <h4> 8322 <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a> 8323 </h4> 8324 8325 <div> 8326 8327 <h5>Syntax:</h5> 8328 <pre> 8329 declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>) 8330 </pre> 8331 8332 <h5>Overview:</h5> 8333 <p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory 8334 object's lifetime.</p> 8335 8336 <h5>Arguments:</h5> 8337 <p>The first argument is a constant integer representing the size of the 8338 object, or -1 if it is variable sized. The second argument is a pointer to 8339 the object.</p> 8340 8341 <h5>Semantics:</h5> 8342 <p>This intrinsic indicates that before this point in the code, the value of the 8343 memory pointed to by <tt>ptr</tt> is dead. This means that it is known to 8344 never be used and has an undefined value. A load from the pointer that 8345 precedes this intrinsic can be replaced with 8346 <tt>'<a href="#undefvalues">undef</a>'</tt>.</p> 8347 8348 </div> 8349 8350 <!-- _______________________________________________________________________ --> 8351 <h4> 8352 <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a> 8353 </h4> 8354 8355 <div> 8356 8357 <h5>Syntax:</h5> 8358 <pre> 8359 declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>) 8360 </pre> 8361 8362 <h5>Overview:</h5> 8363 <p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory 8364 object's lifetime.</p> 8365 8366 <h5>Arguments:</h5> 8367 <p>The first argument is a constant integer representing the size of the 8368 object, or -1 if it is variable sized. The second argument is a pointer to 8369 the object.</p> 8370 8371 <h5>Semantics:</h5> 8372 <p>This intrinsic indicates that after this point in the code, the value of the 8373 memory pointed to by <tt>ptr</tt> is dead. This means that it is known to 8374 never be used and has an undefined value. Any stores into the memory object 8375 following this intrinsic may be removed as dead. 8376 8377 </div> 8378 8379 <!-- _______________________________________________________________________ --> 8380 <h4> 8381 <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a> 8382 </h4> 8383 8384 <div> 8385 8386 <h5>Syntax:</h5> 8387 <pre> 8388 declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) 8389 </pre> 8390 8391 <h5>Overview:</h5> 8392 <p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of 8393 a memory object will not change.</p> 8394 8395 <h5>Arguments:</h5> 8396 <p>The first argument is a constant integer representing the size of the 8397 object, or -1 if it is variable sized. The second argument is a pointer to 8398 the object.</p> 8399 8400 <h5>Semantics:</h5> 8401 <p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses 8402 the return value, the referenced memory location is constant and 8403 unchanging.</p> 8404 8405 </div> 8406 8407 <!-- _______________________________________________________________________ --> 8408 <h4> 8409 <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a> 8410 </h4> 8411 8412 <div> 8413 8414 <h5>Syntax:</h5> 8415 <pre> 8416 declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>) 8417 </pre> 8418 8419 <h5>Overview:</h5> 8420 <p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of 8421 a memory object are mutable.</p> 8422 8423 <h5>Arguments:</h5> 8424 <p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic. 8425 The second argument is a constant integer representing the size of the 8426 object, or -1 if it is variable sized and the third argument is a pointer 8427 to the object.</p> 8428 8429 <h5>Semantics:</h5> 8430 <p>This intrinsic indicates that the memory is mutable again.</p> 8431 8432 </div> 8433 8434 </div> 8435 8436 <!-- ======================================================================= --> 8437 <h3> 8438 <a name="int_general">General Intrinsics</a> 8439 </h3> 8440 8441 <div> 8442 8443 <p>This class of intrinsics is designed to be generic and has no specific 8444 purpose.</p> 8445 8446 <!-- _______________________________________________________________________ --> 8447 <h4> 8448 <a name="int_var_annotation">'<tt>llvm.var.annotation</tt>' Intrinsic</a> 8449 </h4> 8450 8451 <div> 8452 8453 <h5>Syntax:</h5> 8454 <pre> 8455 declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>) 8456 </pre> 8457 8458 <h5>Overview:</h5> 8459 <p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p> 8460 8461 <h5>Arguments:</h5> 8462 <p>The first argument is a pointer to a value, the second is a pointer to a 8463 global string, the third is a pointer to a global string which is the source 8464 file name, and the last argument is the line number.</p> 8465 8466 <h5>Semantics:</h5> 8467 <p>This intrinsic allows annotation of local variables with arbitrary strings. 8468 This can be useful for special purpose optimizations that want to look for 8469 these annotations. These have no other defined use; they are ignored by code 8470 generation and optimization.</p> 8471 8472 </div> 8473 8474 <!-- _______________________________________________________________________ --> 8475 <h4> 8476 <a name="int_annotation">'<tt>llvm.annotation.*</tt>' Intrinsic</a> 8477 </h4> 8478 8479 <div> 8480 8481 <h5>Syntax:</h5> 8482 <p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on 8483 any integer bit width.</p> 8484 8485 <pre> 8486 declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>) 8487 declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>) 8488 declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>) 8489 declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>) 8490 declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>) 8491 </pre> 8492 8493 <h5>Overview:</h5> 8494 <p>The '<tt>llvm.annotation</tt>' intrinsic.</p> 8495 8496 <h5>Arguments:</h5> 8497 <p>The first argument is an integer value (result of some expression), the 8498 second is a pointer to a global string, the third is a pointer to a global 8499 string which is the source file name, and the last argument is the line 8500 number. It returns the value of the first argument.</p> 8501 8502 <h5>Semantics:</h5> 8503 <p>This intrinsic allows annotations to be put on arbitrary expressions with 8504 arbitrary strings. This can be useful for special purpose optimizations that 8505 want to look for these annotations. These have no other defined use; they 8506 are ignored by code generation and optimization.</p> 8507 8508 </div> 8509 8510 <!-- _______________________________________________________________________ --> 8511 <h4> 8512 <a name="int_trap">'<tt>llvm.trap</tt>' Intrinsic</a> 8513 </h4> 8514 8515 <div> 8516 8517 <h5>Syntax:</h5> 8518 <pre> 8519 declare void @llvm.trap() 8520 </pre> 8521 8522 <h5>Overview:</h5> 8523 <p>The '<tt>llvm.trap</tt>' intrinsic.</p> 8524 8525 <h5>Arguments:</h5> 8526 <p>None.</p> 8527 8528 <h5>Semantics:</h5> 8529 <p>This intrinsics is lowered to the target dependent trap instruction. If the 8530 target does not have a trap instruction, this intrinsic will be lowered to 8531 the call of the <tt>abort()</tt> function.</p> 8532 8533 </div> 8534 8535 <!-- _______________________________________________________________________ --> 8536 <h4> 8537 <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a> 8538 </h4> 8539 8540 <div> 8541 8542 <h5>Syntax:</h5> 8543 <pre> 8544 declare void @llvm.stackprotector(i8* <guard>, i8** <slot>) 8545 </pre> 8546 8547 <h5>Overview:</h5> 8548 <p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and 8549 stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to 8550 ensure that it is placed on the stack before local variables.</p> 8551 8552 <h5>Arguments:</h5> 8553 <p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer 8554 arguments. The first argument is the value loaded from the stack 8555 guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt> 8556 that has enough space to hold the value of the guard.</p> 8557 8558 <h5>Semantics:</h5> 8559 <p>This intrinsic causes the prologue/epilogue inserter to force the position of 8560 the <tt>AllocaInst</tt> stack slot to be before local variables on the 8561 stack. This is to ensure that if a local variable on the stack is 8562 overwritten, it will destroy the value of the guard. When the function exits, 8563 the guard on the stack is checked against the original guard. If they are 8564 different, then the program aborts by calling the <tt>__stack_chk_fail()</tt> 8565 function.</p> 8566 8567 </div> 8568 8569 <!-- _______________________________________________________________________ --> 8570 <h4> 8571 <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a> 8572 </h4> 8573 8574 <div> 8575 8576 <h5>Syntax:</h5> 8577 <pre> 8578 declare i32 @llvm.objectsize.i32(i8* <object>, i1 <type>) 8579 declare i64 @llvm.objectsize.i64(i8* <object>, i1 <type>) 8580 </pre> 8581 8582 <h5>Overview:</h5> 8583 <p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information to 8584 the optimizers to determine at compile time whether a) an operation (like 8585 memcpy) will overflow a buffer that corresponds to an object, or b) that a 8586 runtime check for overflow isn't necessary. An object in this context means 8587 an allocation of a specific class, structure, array, or other object.</p> 8588 8589 <h5>Arguments:</h5> 8590 <p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments. The first 8591 argument is a pointer to or into the <tt>object</tt>. The second argument 8592 is a boolean 0 or 1. This argument determines whether you want the 8593 maximum (0) or minimum (1) bytes remaining. This needs to be a literal 0 or 8594 1, variables are not allowed.</p> 8595 8596 <h5>Semantics:</h5> 8597 <p>The <tt>llvm.objectsize</tt> intrinsic is lowered to either a constant 8598 representing the size of the object concerned, or <tt>i32/i64 -1 or 0</tt>, 8599 depending on the <tt>type</tt> argument, if the size cannot be determined at 8600 compile time.</p> 8601 8602 </div> 8603 8604 </div> 8605 8606 </div> 8607 8608 <!-- *********************************************************************** --> 8609 <hr> 8610 <address> 8611 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img 8612 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> 8613 <a href="http://validator.w3.org/check/referer"><img 8614 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> 8615 8616 <a href="mailto:sabre (a] nondot.org">Chris Lattner</a><br> 8617 <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> 8618 Last modified: $Date$ 8619 </address> 8620 8621 </body> 8622 </html> 8623
