1============================== 2LLVM Language Reference Manual 3============================== 4 5.. contents:: 6 :local: 7 :depth: 4 8 9Abstract 10======== 11 12This document is a reference manual for the LLVM assembly language. LLVM 13is a Static Single Assignment (SSA) based representation that provides 14type safety, low-level operations, flexibility, and the capability of 15representing 'all' high-level languages cleanly. It is the common code 16representation used throughout all phases of the LLVM compilation 17strategy. 18 19Introduction 20============ 21 22The LLVM code representation is designed to be used in three different 23forms: as an in-memory compiler IR, as an on-disk bitcode representation 24(suitable for fast loading by a Just-In-Time compiler), and as a human 25readable assembly language representation. This allows LLVM to provide a 26powerful intermediate representation for efficient compiler 27transformations and analysis, while providing a natural means to debug 28and visualize the transformations. The three different forms of LLVM are 29all equivalent. This document describes the human readable 30representation and notation. 31 32The LLVM representation aims to be light-weight and low-level while 33being expressive, typed, and extensible at the same time. It aims to be 34a "universal IR" of sorts, by being at a low enough level that 35high-level ideas may be cleanly mapped to it (similar to how 36microprocessors are "universal IR's", allowing many source languages to 37be mapped to them). By providing type information, LLVM can be used as 38the target of optimizations: for example, through pointer analysis, it 39can be proven that a C automatic variable is never accessed outside of 40the current function, allowing it to be promoted to a simple SSA value 41instead of a memory location. 42 43.. _wellformed: 44 45Well-Formedness 46--------------- 47 48It is important to note that this document describes 'well formed' LLVM 49assembly language. There is a difference between what the parser accepts 50and what is considered 'well formed'. For example, the following 51instruction is syntactically okay, but not well formed: 52 53.. code-block:: llvm 54 55 %x = add i32 1, %x 56 57because the definition of ``%x`` does not dominate all of its uses. The 58LLVM infrastructure provides a verification pass that may be used to 59verify that an LLVM module is well formed. This pass is automatically 60run by the parser after parsing input assembly and by the optimizer 61before it outputs bitcode. The violations pointed out by the verifier 62pass indicate bugs in transformation passes or input to the parser. 63 64.. _identifiers: 65 66Identifiers 67=========== 68 69LLVM identifiers come in two basic types: global and local. Global 70identifiers (functions, global variables) begin with the ``'@'`` 71character. Local identifiers (register names, types) begin with the 72``'%'`` character. Additionally, there are three different formats for 73identifiers, for different purposes: 74 75#. Named values are represented as a string of characters with their 76 prefix. For example, ``%foo``, ``@DivisionByZero``, 77 ``%a.really.long.identifier``. The actual regular expression used is 78 '``[%@][-a-zA-Z$._][-a-zA-Z$._0-9]*``'. Identifiers that require other 79 characters in their names can be surrounded with quotes. Special 80 characters may be escaped using ``"\xx"`` where ``xx`` is the ASCII 81 code for the character in hexadecimal. In this way, any character can 82 be used in a name value, even quotes themselves. The ``"\01"`` prefix 83 can be used on global values to suppress mangling. 84#. Unnamed values are represented as an unsigned numeric value with 85 their prefix. For example, ``%12``, ``@2``, ``%44``. 86#. Constants, which are described in the section Constants_ below. 87 88LLVM requires that values start with a prefix for two reasons: Compilers 89don't need to worry about name clashes with reserved words, and the set 90of reserved words may be expanded in the future without penalty. 91Additionally, unnamed identifiers allow a compiler to quickly come up 92with a temporary variable without having to avoid symbol table 93conflicts. 94 95Reserved words in LLVM are very similar to reserved words in other 96languages. There are keywords for different opcodes ('``add``', 97'``bitcast``', '``ret``', etc...), for primitive type names ('``void``', 98'``i32``', etc...), and others. These reserved words cannot conflict 99with variable names, because none of them start with a prefix character 100(``'%'`` or ``'@'``). 101 102Here is an example of LLVM code to multiply the integer variable 103'``%X``' by 8: 104 105The easy way: 106 107.. code-block:: llvm 108 109 %result = mul i32 %X, 8 110 111After strength reduction: 112 113.. code-block:: llvm 114 115 %result = shl i32 %X, 3 116 117And the hard way: 118 119.. code-block:: llvm 120 121 %0 = add i32 %X, %X ; yields i32:%0 122 %1 = add i32 %0, %0 ; yields i32:%1 123 %result = add i32 %1, %1 124 125This last way of multiplying ``%X`` by 8 illustrates several important 126lexical features of LLVM: 127 128#. Comments are delimited with a '``;``' and go until the end of line. 129#. Unnamed temporaries are created when the result of a computation is 130 not assigned to a named value. 131#. Unnamed temporaries are numbered sequentially (using a per-function 132 incrementing counter, starting with 0). Note that basic blocks and unnamed 133 function parameters are included in this numbering. For example, if the 134 entry basic block is not given a label name and all function parameters are 135 named, then it will get number 0. 136 137It also shows a convention that we follow in this document. When 138demonstrating instructions, we will follow an instruction with a comment 139that defines the type and name of value produced. 140 141High Level Structure 142==================== 143 144Module Structure 145---------------- 146 147LLVM programs are composed of ``Module``'s, each of which is a 148translation unit of the input programs. Each module consists of 149functions, global variables, and symbol table entries. Modules may be 150combined together with the LLVM linker, which merges function (and 151global variable) definitions, resolves forward declarations, and merges 152symbol table entries. Here is an example of the "hello world" module: 153 154.. code-block:: llvm 155 156 ; Declare the string constant as a global constant. 157 @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" 158 159 ; External declaration of the puts function 160 declare i32 @puts(i8* nocapture) nounwind 161 162 ; Definition of main function 163 define i32 @main() { ; i32()* 164 ; Convert [13 x i8]* to i8*... 165 %cast210 = getelementptr [13 x i8], [13 x i8]* @.str, i64 0, i64 0 166 167 ; Call puts function to write out the string to stdout. 168 call i32 @puts(i8* %cast210) 169 ret i32 0 170 } 171 172 ; Named metadata 173 !0 = !{i32 42, null, !"string"} 174 !foo = !{!0} 175 176This example is made up of a :ref:`global variable <globalvars>` named 177"``.str``", an external declaration of the "``puts``" function, a 178:ref:`function definition <functionstructure>` for "``main``" and 179:ref:`named metadata <namedmetadatastructure>` "``foo``". 180 181In general, a module is made up of a list of global values (where both 182functions and global variables are global values). Global values are 183represented by a pointer to a memory location (in this case, a pointer 184to an array of char, and a pointer to a function), and have one of the 185following :ref:`linkage types <linkage>`. 186 187.. _linkage: 188 189Linkage Types 190------------- 191 192All Global Variables and Functions have one of the following types of 193linkage: 194 195``private`` 196 Global values with "``private``" linkage are only directly 197 accessible by objects in the current module. In particular, linking 198 code into a module with a private global value may cause the 199 private to be renamed as necessary to avoid collisions. Because the 200 symbol is private to the module, all references can be updated. This 201 doesn't show up in any symbol table in the object file. 202``internal`` 203 Similar to private, but the value shows as a local symbol 204 (``STB_LOCAL`` in the case of ELF) in the object file. This 205 corresponds to the notion of the '``static``' keyword in C. 206``available_externally`` 207 Globals with "``available_externally``" linkage are never emitted into 208 the object file corresponding to the LLVM module. From the linker's 209 perspective, an ``available_externally`` global is equivalent to 210 an external declaration. They exist to allow inlining and other 211 optimizations to take place given knowledge of the definition of the 212 global, which is known to be somewhere outside the module. Globals 213 with ``available_externally`` linkage are allowed to be discarded at 214 will, and allow inlining and other optimizations. This linkage type is 215 only allowed on definitions, not declarations. 216``linkonce`` 217 Globals with "``linkonce``" linkage are merged with other globals of 218 the same name when linkage occurs. This can be used to implement 219 some forms of inline functions, templates, or other code which must 220 be generated in each translation unit that uses it, but where the 221 body may be overridden with a more definitive definition later. 222 Unreferenced ``linkonce`` globals are allowed to be discarded. Note 223 that ``linkonce`` linkage does not actually allow the optimizer to 224 inline the body of this function into callers because it doesn't 225 know if this definition of the function is the definitive definition 226 within the program or whether it will be overridden by a stronger 227 definition. To enable inlining and other optimizations, use 228 "``linkonce_odr``" linkage. 229``weak`` 230 "``weak``" linkage has the same merging semantics as ``linkonce`` 231 linkage, except that unreferenced globals with ``weak`` linkage may 232 not be discarded. This is used for globals that are declared "weak" 233 in C source code. 234``common`` 235 "``common``" linkage is most similar to "``weak``" linkage, but they 236 are used for tentative definitions in C, such as "``int X;``" at 237 global scope. Symbols with "``common``" linkage are merged in the 238 same way as ``weak symbols``, and they may not be deleted if 239 unreferenced. ``common`` symbols may not have an explicit section, 240 must have a zero initializer, and may not be marked 241 ':ref:`constant <globalvars>`'. Functions and aliases may not have 242 common linkage. 243 244.. _linkage_appending: 245 246``appending`` 247 "``appending``" linkage may only be applied to global variables of 248 pointer to array type. When two global variables with appending 249 linkage are linked together, the two global arrays are appended 250 together. This is the LLVM, typesafe, equivalent of having the 251 system linker append together "sections" with identical names when 252 .o files are linked. 253 254 Unfortunately this doesn't correspond to any feature in .o files, so it 255 can only be used for variables like ``llvm.global_ctors`` which llvm 256 interprets specially. 257 258``extern_weak`` 259 The semantics of this linkage follow the ELF object file model: the 260 symbol is weak until linked, if not linked, the symbol becomes null 261 instead of being an undefined reference. 262``linkonce_odr``, ``weak_odr`` 263 Some languages allow differing globals to be merged, such as two 264 functions with different semantics. Other languages, such as 265 ``C++``, ensure that only equivalent globals are ever merged (the 266 "one definition rule" --- "ODR"). Such languages can use the 267 ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the 268 global will only be merged with equivalent globals. These linkage 269 types are otherwise the same as their non-``odr`` versions. 270``external`` 271 If none of the above identifiers are used, the global is externally 272 visible, meaning that it participates in linkage and can be used to 273 resolve external symbol references. 274 275It is illegal for a function *declaration* to have any linkage type 276other than ``external`` or ``extern_weak``. 277 278.. _callingconv: 279 280Calling Conventions 281------------------- 282 283LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and 284:ref:`invokes <i_invoke>` can all have an optional calling convention 285specified for the call. The calling convention of any pair of dynamic 286caller/callee must match, or the behavior of the program is undefined. 287The following calling conventions are supported by LLVM, and more may be 288added in the future: 289 290"``ccc``" - The C calling convention 291 This calling convention (the default if no other calling convention 292 is specified) matches the target C calling conventions. This calling 293 convention supports varargs function calls and tolerates some 294 mismatch in the declared prototype and implemented declaration of 295 the function (as does normal C). 296"``fastcc``" - The fast calling convention 297 This calling convention attempts to make calls as fast as possible 298 (e.g. by passing things in registers). This calling convention 299 allows the target to use whatever tricks it wants to produce fast 300 code for the target, without having to conform to an externally 301 specified ABI (Application Binary Interface). `Tail calls can only 302 be optimized when this, the GHC or the HiPE convention is 303 used. <CodeGenerator.html#id80>`_ This calling convention does not 304 support varargs and requires the prototype of all callees to exactly 305 match the prototype of the function definition. 306"``coldcc``" - The cold calling convention 307 This calling convention attempts to make code in the caller as 308 efficient as possible under the assumption that the call is not 309 commonly executed. As such, these calls often preserve all registers 310 so that the call does not break any live ranges in the caller side. 311 This calling convention does not support varargs and requires the 312 prototype of all callees to exactly match the prototype of the 313 function definition. Furthermore the inliner doesn't consider such function 314 calls for inlining. 315"``cc 10``" - GHC convention 316 This calling convention has been implemented specifically for use by 317 the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_. 318 It passes everything in registers, going to extremes to achieve this 319 by disabling callee save registers. This calling convention should 320 not be used lightly but only for specific situations such as an 321 alternative to the *register pinning* performance technique often 322 used when implementing functional programming languages. At the 323 moment only X86 supports this convention and it has the following 324 limitations: 325 326 - On *X86-32* only supports up to 4 bit type parameters. No 327 floating-point types are supported. 328 - On *X86-64* only supports up to 10 bit type parameters and 6 329 floating-point parameters. 330 331 This calling convention supports `tail call 332 optimization <CodeGenerator.html#id80>`_ but requires both the 333 caller and callee are using it. 334"``cc 11``" - The HiPE calling convention 335 This calling convention has been implemented specifically for use by 336 the `High-Performance Erlang 337 (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the* 338 native code compiler of the `Ericsson's Open Source Erlang/OTP 339 system <http://www.erlang.org/download.shtml>`_. It uses more 340 registers for argument passing than the ordinary C calling 341 convention and defines no callee-saved registers. The calling 342 convention properly supports `tail call 343 optimization <CodeGenerator.html#id80>`_ but requires that both the 344 caller and the callee use it. It uses a *register pinning* 345 mechanism, similar to GHC's convention, for keeping frequently 346 accessed runtime components pinned to specific hardware registers. 347 At the moment only X86 supports this convention (both 32 and 64 348 bit). 349"``webkit_jscc``" - WebKit's JavaScript calling convention 350 This calling convention has been implemented for `WebKit FTL JIT 351 <https://trac.webkit.org/wiki/FTLJIT>`_. It passes arguments on the 352 stack right to left (as cdecl does), and returns a value in the 353 platform's customary return register. 354"``anyregcc``" - Dynamic calling convention for code patching 355 This is a special convention that supports patching an arbitrary code 356 sequence in place of a call site. This convention forces the call 357 arguments into registers but allows them to be dynamically 358 allocated. This can currently only be used with calls to 359 llvm.experimental.patchpoint because only this intrinsic records 360 the location of its arguments in a side table. See :doc:`StackMaps`. 361"``preserve_mostcc``" - The `PreserveMost` calling convention 362 This calling convention attempts to make the code in the caller as 363 unintrusive as possible. This convention behaves identically to the `C` 364 calling convention on how arguments and return values are passed, but it 365 uses a different set of caller/callee-saved registers. This alleviates the 366 burden of saving and recovering a large register set before and after the 367 call in the caller. If the arguments are passed in callee-saved registers, 368 then they will be preserved by the callee across the call. This doesn't 369 apply for values returned in callee-saved registers. 370 371 - On X86-64 the callee preserves all general purpose registers, except for 372 R11. R11 can be used as a scratch register. Floating-point registers 373 (XMMs/YMMs) are not preserved and need to be saved by the caller. 374 375 The idea behind this convention is to support calls to runtime functions 376 that have a hot path and a cold path. The hot path is usually a small piece 377 of code that doesn't use many registers. The cold path might need to call out to 378 another function and therefore only needs to preserve the caller-saved 379 registers, which haven't already been saved by the caller. The 380 `PreserveMost` calling convention is very similar to the `cold` calling 381 convention in terms of caller/callee-saved registers, but they are used for 382 different types of function calls. `coldcc` is for function calls that are 383 rarely executed, whereas `preserve_mostcc` function calls are intended to be 384 on the hot path and definitely executed a lot. Furthermore `preserve_mostcc` 385 doesn't prevent the inliner from inlining the function call. 386 387 This calling convention will be used by a future version of the ObjectiveC 388 runtime and should therefore still be considered experimental at this time. 389 Although this convention was created to optimize certain runtime calls to 390 the ObjectiveC runtime, it is not limited to this runtime and might be used 391 by other runtimes in the future too. The current implementation only 392 supports X86-64, but the intention is to support more architectures in the 393 future. 394"``preserve_allcc``" - The `PreserveAll` calling convention 395 This calling convention attempts to make the code in the caller even less 396 intrusive than the `PreserveMost` calling convention. This calling 397 convention also behaves identical to the `C` calling convention on how 398 arguments and return values are passed, but it uses a different set of 399 caller/callee-saved registers. This removes the burden of saving and 400 recovering a large register set before and after the call in the caller. If 401 the arguments are passed in callee-saved registers, then they will be 402 preserved by the callee across the call. This doesn't apply for values 403 returned in callee-saved registers. 404 405 - On X86-64 the callee preserves all general purpose registers, except for 406 R11. R11 can be used as a scratch register. Furthermore it also preserves 407 all floating-point registers (XMMs/YMMs). 408 409 The idea behind this convention is to support calls to runtime functions 410 that don't need to call out to any other functions. 411 412 This calling convention, like the `PreserveMost` calling convention, will be 413 used by a future version of the ObjectiveC runtime and should be considered 414 experimental at this time. 415"``cxx_fast_tlscc``" - The `CXX_FAST_TLS` calling convention for access functions 416 Clang generates an access function to access C++-style TLS. The access 417 function generally has an entry block, an exit block and an initialization 418 block that is run at the first time. The entry and exit blocks can access 419 a few TLS IR variables, each access will be lowered to a platform-specific 420 sequence. 421 422 This calling convention aims to minimize overhead in the caller by 423 preserving as many registers as possible (all the registers that are 424 perserved on the fast path, composed of the entry and exit blocks). 425 426 This calling convention behaves identical to the `C` calling convention on 427 how arguments and return values are passed, but it uses a different set of 428 caller/callee-saved registers. 429 430 Given that each platform has its own lowering sequence, hence its own set 431 of preserved registers, we can't use the existing `PreserveMost`. 432 433 - On X86-64 the callee preserves all general purpose registers, except for 434 RDI and RAX. 435"``swiftcc``" - This calling convention is used for Swift language. 436 - On X86-64 RCX and R8 are available for additional integer returns, and 437 XMM2 and XMM3 are available for additional FP/vector returns. 438 - On iOS platforms, we use AAPCS-VFP calling convention. 439"``cc <n>``" - Numbered convention 440 Any calling convention may be specified by number, allowing 441 target-specific calling conventions to be used. Target specific 442 calling conventions start at 64. 443 444More calling conventions can be added/defined on an as-needed basis, to 445support Pascal conventions or any other well-known target-independent 446convention. 447 448.. _visibilitystyles: 449 450Visibility Styles 451----------------- 452 453All Global Variables and Functions have one of the following visibility 454styles: 455 456"``default``" - Default style 457 On targets that use the ELF object file format, default visibility 458 means that the declaration is visible to other modules and, in 459 shared libraries, means that the declared entity may be overridden. 460 On Darwin, default visibility means that the declaration is visible 461 to other modules. Default visibility corresponds to "external 462 linkage" in the language. 463"``hidden``" - Hidden style 464 Two declarations of an object with hidden visibility refer to the 465 same object if they are in the same shared object. Usually, hidden 466 visibility indicates that the symbol will not be placed into the 467 dynamic symbol table, so no other module (executable or shared 468 library) can reference it directly. 469"``protected``" - Protected style 470 On ELF, protected visibility indicates that the symbol will be 471 placed in the dynamic symbol table, but that references within the 472 defining module will bind to the local symbol. That is, the symbol 473 cannot be overridden by another module. 474 475A symbol with ``internal`` or ``private`` linkage must have ``default`` 476visibility. 477 478.. _dllstorageclass: 479 480DLL Storage Classes 481------------------- 482 483All Global Variables, Functions and Aliases can have one of the following 484DLL storage class: 485 486``dllimport`` 487 "``dllimport``" causes the compiler to reference a function or variable via 488 a global pointer to a pointer that is set up by the DLL exporting the 489 symbol. On Microsoft Windows targets, the pointer name is formed by 490 combining ``__imp_`` and the function or variable name. 491``dllexport`` 492 "``dllexport``" causes the compiler to provide a global pointer to a pointer 493 in a DLL, so that it can be referenced with the ``dllimport`` attribute. On 494 Microsoft Windows targets, the pointer name is formed by combining 495 ``__imp_`` and the function or variable name. Since this storage class 496 exists for defining a dll interface, the compiler, assembler and linker know 497 it is externally referenced and must refrain from deleting the symbol. 498 499.. _tls_model: 500 501Thread Local Storage Models 502--------------------------- 503 504A variable may be defined as ``thread_local``, which means that it will 505not be shared by threads (each thread will have a separated copy of the 506variable). Not all targets support thread-local variables. Optionally, a 507TLS model may be specified: 508 509``localdynamic`` 510 For variables that are only used within the current shared library. 511``initialexec`` 512 For variables in modules that will not be loaded dynamically. 513``localexec`` 514 For variables defined in the executable and only used within it. 515 516If no explicit model is given, the "general dynamic" model is used. 517 518The models correspond to the ELF TLS models; see `ELF Handling For 519Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for 520more information on under which circumstances the different models may 521be used. The target may choose a different TLS model if the specified 522model is not supported, or if a better choice of model can be made. 523 524A model can also be specified in an alias, but then it only governs how 525the alias is accessed. It will not have any effect in the aliasee. 526 527For platforms without linker support of ELF TLS model, the -femulated-tls 528flag can be used to generate GCC compatible emulated TLS code. 529 530.. _runtime_preemption_model: 531 532Runtime Preemption Specifiers 533----------------------------- 534 535Global variables, functions and aliases may have an optional runtime preemption 536specifier. If a preemption specifier isn't given explicitly, then a 537symbol is assumed to be ``dso_preemptable``. 538 539``dso_preemptable`` 540 Indicates that the function or variable may be replaced by a symbol from 541 outside the linkage unit at runtime. 542 543``dso_local`` 544 The compiler may assume that a function or variable marked as ``dso_local`` 545 will resolve to a symbol within the same linkage unit. Direct access will 546 be generated even if the definition is not within this compilation unit. 547 548.. _namedtypes: 549 550Structure Types 551--------------- 552 553LLVM IR allows you to specify both "identified" and "literal" :ref:`structure 554types <t_struct>`. Literal types are uniqued structurally, but identified types 555are never uniqued. An :ref:`opaque structural type <t_opaque>` can also be used 556to forward declare a type that is not yet available. 557 558An example of an identified structure specification is: 559 560.. code-block:: llvm 561 562 %mytype = type { %mytype*, i32 } 563 564Prior to the LLVM 3.0 release, identified types were structurally uniqued. Only 565literal types are uniqued in recent versions of LLVM. 566 567.. _nointptrtype: 568 569Non-Integral Pointer Type 570------------------------- 571 572Note: non-integral pointer types are a work in progress, and they should be 573considered experimental at this time. 574 575LLVM IR optionally allows the frontend to denote pointers in certain address 576spaces as "non-integral" via the :ref:`datalayout string<langref_datalayout>`. 577Non-integral pointer types represent pointers that have an *unspecified* bitwise 578representation; that is, the integral representation may be target dependent or 579unstable (not backed by a fixed integer). 580 581``inttoptr`` instructions converting integers to non-integral pointer types are 582ill-typed, and so are ``ptrtoint`` instructions converting values of 583non-integral pointer types to integers. Vector versions of said instructions 584are ill-typed as well. 585 586.. _globalvars: 587 588Global Variables 589---------------- 590 591Global variables define regions of memory allocated at compilation time 592instead of run-time. 593 594Global variable definitions must be initialized. 595 596Global variables in other translation units can also be declared, in which 597case they don't have an initializer. 598 599Either global variable definitions or declarations may have an explicit section 600to be placed in and may have an optional explicit alignment specified. If there 601is a mismatch between the explicit or inferred section information for the 602variable declaration and its definition the resulting behavior is undefined. 603 604A variable may be defined as a global ``constant``, which indicates that 605the contents of the variable will **never** be modified (enabling better 606optimization, allowing the global data to be placed in the read-only 607section of an executable, etc). Note that variables that need runtime 608initialization cannot be marked ``constant`` as there is a store to the 609variable. 610 611LLVM explicitly allows *declarations* of global variables to be marked 612constant, even if the final definition of the global is not. This 613capability can be used to enable slightly better optimization of the 614program, but requires the language definition to guarantee that 615optimizations based on the 'constantness' are valid for the translation 616units that do not include the definition. 617 618As SSA values, global variables define pointer values that are in scope 619(i.e. they dominate) all basic blocks in the program. Global variables 620always define a pointer to their "content" type because they describe a 621region of memory, and all memory objects in LLVM are accessed through 622pointers. 623 624Global variables can be marked with ``unnamed_addr`` which indicates 625that the address is not significant, only the content. Constants marked 626like this can be merged with other constants if they have the same 627initializer. Note that a constant with significant address *can* be 628merged with a ``unnamed_addr`` constant, the result being a constant 629whose address is significant. 630 631If the ``local_unnamed_addr`` attribute is given, the address is known to 632not be significant within the module. 633 634A global variable may be declared to reside in a target-specific 635numbered address space. For targets that support them, address spaces 636may affect how optimizations are performed and/or what target 637instructions are used to access the variable. The default address space 638is zero. The address space qualifier must precede any other attributes. 639 640LLVM allows an explicit section to be specified for globals. If the 641target supports it, it will emit globals to the section specified. 642Additionally, the global can placed in a comdat if the target has the necessary 643support. 644 645External declarations may have an explicit section specified. Section 646information is retained in LLVM IR for targets that make use of this 647information. Attaching section information to an external declaration is an 648assertion that its definition is located in the specified section. If the 649definition is located in a different section, the behavior is undefined. 650 651By default, global initializers are optimized by assuming that global 652variables defined within the module are not modified from their 653initial values before the start of the global initializer. This is 654true even for variables potentially accessible from outside the 655module, including those with external linkage or appearing in 656``@llvm.used`` or dllexported variables. This assumption may be suppressed 657by marking the variable with ``externally_initialized``. 658 659An explicit alignment may be specified for a global, which must be a 660power of 2. If not present, or if the alignment is set to zero, the 661alignment of the global is set by the target to whatever it feels 662convenient. If an explicit alignment is specified, the global is forced 663to have exactly that alignment. Targets and optimizers are not allowed 664to over-align the global if the global has an assigned section. In this 665case, the extra alignment could be observable: for example, code could 666assume that the globals are densely packed in their section and try to 667iterate over them as an array, alignment padding would break this 668iteration. The maximum alignment is ``1 << 29``. 669 670Globals can also have a :ref:`DLL storage class <dllstorageclass>`, 671an optional :ref:`runtime preemption specifier <runtime_preemption_model>`, 672an optional :ref:`global attributes <glattrs>` and 673an optional list of attached :ref:`metadata <metadata>`. 674 675Variables and aliases can have a 676:ref:`Thread Local Storage Model <tls_model>`. 677 678Syntax:: 679 680 @<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility] 681 [DLLStorageClass] [ThreadLocal] 682 [(unnamed_addr|local_unnamed_addr)] [AddrSpace] 683 [ExternallyInitialized] 684 <global | constant> <Type> [<InitializerConstant>] 685 [, section "name"] [, comdat [($name)]] 686 [, align <Alignment>] (, !name !N)* 687 688For example, the following defines a global in a numbered address space 689with an initializer, section, and alignment: 690 691.. code-block:: llvm 692 693 @G = addrspace(5) constant float 1.0, section "foo", align 4 694 695The following example just declares a global variable 696 697.. code-block:: llvm 698 699 @G = external global i32 700 701The following example defines a thread-local global with the 702``initialexec`` TLS model: 703 704.. code-block:: llvm 705 706 @G = thread_local(initialexec) global i32 0, align 4 707 708.. _functionstructure: 709 710Functions 711--------- 712 713LLVM function definitions consist of the "``define``" keyword, an 714optional :ref:`linkage type <linkage>`, an optional :ref:`runtime preemption 715specifier <runtime_preemption_model>`, an optional :ref:`visibility 716style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, 717an optional :ref:`calling convention <callingconv>`, 718an optional ``unnamed_addr`` attribute, a return type, an optional 719:ref:`parameter attribute <paramattrs>` for the return type, a function 720name, a (possibly empty) argument list (each with optional :ref:`parameter 721attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`, 722an optional address space, an optional section, an optional alignment, 723an optional :ref:`comdat <langref_comdats>`, 724an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`, 725an optional :ref:`prologue <prologuedata>`, 726an optional :ref:`personality <personalityfn>`, 727an optional list of attached :ref:`metadata <metadata>`, 728an opening curly brace, a list of basic blocks, and a closing curly brace. 729 730LLVM function declarations consist of the "``declare``" keyword, an 731optional :ref:`linkage type <linkage>`, an optional :ref:`visibility style 732<visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, an 733optional :ref:`calling convention <callingconv>`, an optional ``unnamed_addr`` 734or ``local_unnamed_addr`` attribute, an optional address space, a return type, 735an optional :ref:`parameter attribute <paramattrs>` for the return type, a function name, a possibly 736empty list of arguments, an optional alignment, an optional :ref:`garbage 737collector name <gc>`, an optional :ref:`prefix <prefixdata>`, and an optional 738:ref:`prologue <prologuedata>`. 739 740A function definition contains a list of basic blocks, forming the CFG (Control 741Flow Graph) for the function. Each basic block may optionally start with a label 742(giving the basic block a symbol table entry), contains a list of instructions, 743and ends with a :ref:`terminator <terminators>` instruction (such as a branch or 744function return). If an explicit label name is not provided, a block is assigned 745an implicit numbered label, using the next value from the same counter as used 746for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a 747function entry block does not have an explicit label, it will be assigned label 748"%0", then the first unnamed temporary in that block will be "%1", etc. If a 749numeric label is explicitly specified, it must match the numeric label that 750would be used implicitly. 751 752The first basic block in a function is special in two ways: it is 753immediately executed on entrance to the function, and it is not allowed 754to have predecessor basic blocks (i.e. there can not be any branches to 755the entry block of a function). Because the block can have no 756predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`. 757 758LLVM allows an explicit section to be specified for functions. If the 759target supports it, it will emit functions to the section specified. 760Additionally, the function can be placed in a COMDAT. 761 762An explicit alignment may be specified for a function. If not present, 763or if the alignment is set to zero, the alignment of the function is set 764by the target to whatever it feels convenient. If an explicit alignment 765is specified, the function is forced to have at least that much 766alignment. All alignments must be a power of 2. 767 768If the ``unnamed_addr`` attribute is given, the address is known to not 769be significant and two identical functions can be merged. 770 771If the ``local_unnamed_addr`` attribute is given, the address is known to 772not be significant within the module. 773 774If an explicit address space is not given, it will default to the program 775address space from the :ref:`datalayout string<langref_datalayout>`. 776 777Syntax:: 778 779 define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass] 780 [cconv] [ret attrs] 781 <ResultType> @<FunctionName> ([argument list]) 782 [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs] 783 [section "name"] [comdat [($name)]] [align N] [gc] [prefix Constant] 784 [prologue Constant] [personality Constant] (!name !N)* { ... } 785 786The argument list is a comma separated sequence of arguments where each 787argument is of the following form: 788 789Syntax:: 790 791 <type> [parameter Attrs] [name] 792 793 794.. _langref_aliases: 795 796Aliases 797------- 798 799Aliases, unlike function or variables, don't create any new data. They 800are just a new symbol and metadata for an existing position. 801 802Aliases have a name and an aliasee that is either a global value or a 803constant expression. 804 805Aliases may have an optional :ref:`linkage type <linkage>`, an optional 806:ref:`runtime preemption specifier <runtime_preemption_model>`, an optional 807:ref:`visibility style <visibility>`, an optional :ref:`DLL storage class 808<dllstorageclass>` and an optional :ref:`tls model <tls_model>`. 809 810Syntax:: 811 812 @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee> 813 814The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``, 815``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers 816might not correctly handle dropping a weak symbol that is aliased. 817 818Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as 819the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point 820to the same content. 821 822If the ``local_unnamed_addr`` attribute is given, the address is known to 823not be significant within the module. 824 825Since aliases are only a second name, some restrictions apply, of which 826some can only be checked when producing an object file: 827 828* The expression defining the aliasee must be computable at assembly 829 time. Since it is just a name, no relocations can be used. 830 831* No alias in the expression can be weak as the possibility of the 832 intermediate alias being overridden cannot be represented in an 833 object file. 834 835* No global value in the expression can be a declaration, since that 836 would require a relocation, which is not possible. 837 838.. _langref_ifunc: 839 840IFuncs 841------- 842 843IFuncs, like as aliases, don't create any new data or func. They are just a new 844symbol that dynamic linker resolves at runtime by calling a resolver function. 845 846IFuncs have a name and a resolver that is a function called by dynamic linker 847that returns address of another function associated with the name. 848 849IFunc may have an optional :ref:`linkage type <linkage>` and an optional 850:ref:`visibility style <visibility>`. 851 852Syntax:: 853 854 @<Name> = [Linkage] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver> 855 856 857.. _langref_comdats: 858 859Comdats 860------- 861 862Comdat IR provides access to COFF and ELF object file COMDAT functionality. 863 864Comdats have a name which represents the COMDAT key. All global objects that 865specify this key will only end up in the final object file if the linker chooses 866that key over some other key. Aliases are placed in the same COMDAT that their 867aliasee computes to, if any. 868 869Comdats have a selection kind to provide input on how the linker should 870choose between keys in two different object files. 871 872Syntax:: 873 874 $<Name> = comdat SelectionKind 875 876The selection kind must be one of the following: 877 878``any`` 879 The linker may choose any COMDAT key, the choice is arbitrary. 880``exactmatch`` 881 The linker may choose any COMDAT key but the sections must contain the 882 same data. 883``largest`` 884 The linker will choose the section containing the largest COMDAT key. 885``noduplicates`` 886 The linker requires that only section with this COMDAT key exist. 887``samesize`` 888 The linker may choose any COMDAT key but the sections must contain the 889 same amount of data. 890 891Note that the Mach-O platform doesn't support COMDATs, and ELF and WebAssembly 892only support ``any`` as a selection kind. 893 894Here is an example of a COMDAT group where a function will only be selected if 895the COMDAT key's section is the largest: 896 897.. code-block:: text 898 899 $foo = comdat largest 900 @foo = global i32 2, comdat($foo) 901 902 define void @bar() comdat($foo) { 903 ret void 904 } 905 906As a syntactic sugar the ``$name`` can be omitted if the name is the same as 907the global name: 908 909.. code-block:: text 910 911 $foo = comdat any 912 @foo = global i32 2, comdat 913 914 915In a COFF object file, this will create a COMDAT section with selection kind 916``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol 917and another COMDAT section with selection kind 918``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT 919section and contains the contents of the ``@bar`` symbol. 920 921There are some restrictions on the properties of the global object. 922It, or an alias to it, must have the same name as the COMDAT group when 923targeting COFF. 924The contents and size of this object may be used during link-time to determine 925which COMDAT groups get selected depending on the selection kind. 926Because the name of the object must match the name of the COMDAT group, the 927linkage of the global object must not be local; local symbols can get renamed 928if a collision occurs in the symbol table. 929 930The combined use of COMDATS and section attributes may yield surprising results. 931For example: 932 933.. code-block:: text 934 935 $foo = comdat any 936 $bar = comdat any 937 @g1 = global i32 42, section "sec", comdat($foo) 938 @g2 = global i32 42, section "sec", comdat($bar) 939 940From the object file perspective, this requires the creation of two sections 941with the same name. This is necessary because both globals belong to different 942COMDAT groups and COMDATs, at the object file level, are represented by 943sections. 944 945Note that certain IR constructs like global variables and functions may 946create COMDATs in the object file in addition to any which are specified using 947COMDAT IR. This arises when the code generator is configured to emit globals 948in individual sections (e.g. when `-data-sections` or `-function-sections` 949is supplied to `llc`). 950 951.. _namedmetadatastructure: 952 953Named Metadata 954-------------- 955 956Named metadata is a collection of metadata. :ref:`Metadata 957nodes <metadata>` (but not metadata strings) are the only valid 958operands for a named metadata. 959 960#. Named metadata are represented as a string of characters with the 961 metadata prefix. The rules for metadata names are the same as for 962 identifiers, but quoted names are not allowed. ``"\xx"`` type escapes 963 are still valid, which allows any character to be part of a name. 964 965Syntax:: 966 967 ; Some unnamed metadata nodes, which are referenced by the named metadata. 968 !0 = !{!"zero"} 969 !1 = !{!"one"} 970 !2 = !{!"two"} 971 ; A named metadata. 972 !name = !{!0, !1, !2} 973 974.. _paramattrs: 975 976Parameter Attributes 977-------------------- 978 979The return type and each parameter of a function type may have a set of 980*parameter attributes* associated with them. Parameter attributes are 981used to communicate additional information about the result or 982parameters of a function. Parameter attributes are considered to be part 983of the function, not of the function type, so functions with different 984parameter attributes can have the same function type. 985 986Parameter attributes are simple keywords that follow the type specified. 987If multiple parameter attributes are needed, they are space separated. 988For example: 989 990.. code-block:: llvm 991 992 declare i32 @printf(i8* noalias nocapture, ...) 993 declare i32 @atoi(i8 zeroext) 994 declare signext i8 @returns_signed_char() 995 996Note that any attributes for the function result (``nounwind``, 997``readonly``) come immediately after the argument list. 998 999Currently, only the following parameter attributes are defined: 1000 1001``zeroext`` 1002 This indicates to the code generator that the parameter or return 1003 value should be zero-extended to the extent required by the target's 1004 ABI by the caller (for a parameter) or the callee (for a return value). 1005``signext`` 1006 This indicates to the code generator that the parameter or return 1007 value should be sign-extended to the extent required by the target's 1008 ABI (which is usually 32-bits) by the caller (for a parameter) or 1009 the callee (for a return value). 1010``inreg`` 1011 This indicates that this parameter or return value should be treated 1012 in a special target-dependent fashion while emitting code for 1013 a function call or return (usually, by putting it in a register as 1014 opposed to memory, though some targets use it to distinguish between 1015 two different kinds of registers). Use of this attribute is 1016 target-specific. 1017``byval`` 1018 This indicates that the pointer parameter should really be passed by 1019 value to the function. The attribute implies that a hidden copy of 1020 the pointee is made between the caller and the callee, so the callee 1021 is unable to modify the value in the caller. This attribute is only 1022 valid on LLVM pointer arguments. It is generally used to pass 1023 structs and arrays by value, but is also valid on pointers to 1024 scalars. The copy is considered to belong to the caller not the 1025 callee (for example, ``readonly`` functions should not write to 1026 ``byval`` parameters). This is not a valid attribute for return 1027 values. 1028 1029 The byval attribute also supports specifying an alignment with the 1030 align attribute. It indicates the alignment of the stack slot to 1031 form and the known alignment of the pointer specified to the call 1032 site. If the alignment is not specified, then the code generator 1033 makes a target-specific assumption. 1034 1035.. _attr_inalloca: 1036 1037``inalloca`` 1038 1039 The ``inalloca`` argument attribute allows the caller to take the 1040 address of outgoing stack arguments. An ``inalloca`` argument must 1041 be a pointer to stack memory produced by an ``alloca`` instruction. 1042 The alloca, or argument allocation, must also be tagged with the 1043 inalloca keyword. Only the last argument may have the ``inalloca`` 1044 attribute, and that argument is guaranteed to be passed in memory. 1045 1046 An argument allocation may be used by a call at most once because 1047 the call may deallocate it. The ``inalloca`` attribute cannot be 1048 used in conjunction with other attributes that affect argument 1049 storage, like ``inreg``, ``nest``, ``sret``, or ``byval``. The 1050 ``inalloca`` attribute also disables LLVM's implicit lowering of 1051 large aggregate return values, which means that frontend authors 1052 must lower them with ``sret`` pointers. 1053 1054 When the call site is reached, the argument allocation must have 1055 been the most recent stack allocation that is still live, or the 1056 behavior is undefined. It is possible to allocate additional stack 1057 space after an argument allocation and before its call site, but it 1058 must be cleared off with :ref:`llvm.stackrestore 1059 <int_stackrestore>`. 1060 1061 See :doc:`InAlloca` for more information on how to use this 1062 attribute. 1063 1064``sret`` 1065 This indicates that the pointer parameter specifies the address of a 1066 structure that is the return value of the function in the source 1067 program. This pointer must be guaranteed by the caller to be valid: 1068 loads and stores to the structure may be assumed by the callee not 1069 to trap and to be properly aligned. This is not a valid attribute 1070 for return values. 1071 1072.. _attr_align: 1073 1074``align <n>`` 1075 This indicates that the pointer value may be assumed by the optimizer to 1076 have the specified alignment. If the pointer value does not have the 1077 specified alignment, behavior is undefined. 1078 1079 Note that this attribute has additional semantics when combined with the 1080 ``byval`` attribute, which are documented there. 1081 1082.. _noalias: 1083 1084``noalias`` 1085 This indicates that objects accessed via pointer values 1086 :ref:`based <pointeraliasing>` on the argument or return value are not also 1087 accessed, during the execution of the function, via pointer values not 1088 *based* on the argument or return value. The attribute on a return value 1089 also has additional semantics described below. The caller shares the 1090 responsibility with the callee for ensuring that these requirements are met. 1091 For further details, please see the discussion of the NoAlias response in 1092 :ref:`alias analysis <Must, May, or No>`. 1093 1094 Note that this definition of ``noalias`` is intentionally similar 1095 to the definition of ``restrict`` in C99 for function arguments. 1096 1097 For function return values, C99's ``restrict`` is not meaningful, 1098 while LLVM's ``noalias`` is. Furthermore, the semantics of the ``noalias`` 1099 attribute on return values are stronger than the semantics of the attribute 1100 when used on function arguments. On function return values, the ``noalias`` 1101 attribute indicates that the function acts like a system memory allocation 1102 function, returning a pointer to allocated storage disjoint from the 1103 storage for any other object accessible to the caller. 1104 1105``nocapture`` 1106 This indicates that the callee does not make any copies of the 1107 pointer that outlive the callee itself. This is not a valid 1108 attribute for return values. Addresses used in volatile operations 1109 are considered to be captured. 1110 1111.. _nest: 1112 1113``nest`` 1114 This indicates that the pointer parameter can be excised using the 1115 :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid 1116 attribute for return values and can only be applied to one parameter. 1117 1118``returned`` 1119 This indicates that the function always returns the argument as its return 1120 value. This is a hint to the optimizer and code generator used when 1121 generating the caller, allowing value propagation, tail call optimization, 1122 and omission of register saves and restores in some cases; it is not 1123 checked or enforced when generating the callee. The parameter and the 1124 function return type must be valid operands for the 1125 :ref:`bitcast instruction <i_bitcast>`. This is not a valid attribute for 1126 return values and can only be applied to one parameter. 1127 1128``nonnull`` 1129 This indicates that the parameter or return pointer is not null. This 1130 attribute may only be applied to pointer typed parameters. This is not 1131 checked or enforced by LLVM; if the parameter or return pointer is null, 1132 the behavior is undefined. 1133 1134``dereferenceable(<n>)`` 1135 This indicates that the parameter or return pointer is dereferenceable. This 1136 attribute may only be applied to pointer typed parameters. A pointer that 1137 is dereferenceable can be loaded from speculatively without a risk of 1138 trapping. The number of bytes known to be dereferenceable must be provided 1139 in parentheses. It is legal for the number of bytes to be less than the 1140 size of the pointee type. The ``nonnull`` attribute does not imply 1141 dereferenceability (consider a pointer to one element past the end of an 1142 array), however ``dereferenceable(<n>)`` does imply ``nonnull`` in 1143 ``addrspace(0)`` (which is the default address space). 1144 1145``dereferenceable_or_null(<n>)`` 1146 This indicates that the parameter or return value isn't both 1147 non-null and non-dereferenceable (up to ``<n>`` bytes) at the same 1148 time. All non-null pointers tagged with 1149 ``dereferenceable_or_null(<n>)`` are ``dereferenceable(<n>)``. 1150 For address space 0 ``dereferenceable_or_null(<n>)`` implies that 1151 a pointer is exactly one of ``dereferenceable(<n>)`` or ``null``, 1152 and in other address spaces ``dereferenceable_or_null(<n>)`` 1153 implies that a pointer is at least one of ``dereferenceable(<n>)`` 1154 or ``null`` (i.e. it may be both ``null`` and 1155 ``dereferenceable(<n>)``). This attribute may only be applied to 1156 pointer typed parameters. 1157 1158``swiftself`` 1159 This indicates that the parameter is the self/context parameter. This is not 1160 a valid attribute for return values and can only be applied to one 1161 parameter. 1162 1163``swifterror`` 1164 This attribute is motivated to model and optimize Swift error handling. It 1165 can be applied to a parameter with pointer to pointer type or a 1166 pointer-sized alloca. At the call site, the actual argument that corresponds 1167 to a ``swifterror`` parameter has to come from a ``swifterror`` alloca or 1168 the ``swifterror`` parameter of the caller. A ``swifterror`` value (either 1169 the parameter or the alloca) can only be loaded and stored from, or used as 1170 a ``swifterror`` argument. This is not a valid attribute for return values 1171 and can only be applied to one parameter. 1172 1173 These constraints allow the calling convention to optimize access to 1174 ``swifterror`` variables by associating them with a specific register at 1175 call boundaries rather than placing them in memory. Since this does change 1176 the calling convention, a function which uses the ``swifterror`` attribute 1177 on a parameter is not ABI-compatible with one which does not. 1178 1179 These constraints also allow LLVM to assume that a ``swifterror`` argument 1180 does not alias any other memory visible within a function and that a 1181 ``swifterror`` alloca passed as an argument does not escape. 1182 1183``immarg`` 1184 This indicates the parameter is required to be an immediate 1185 value. This must be a trivial immediate integer or floating-point 1186 constant. Undef or constant expressions are not valid. This is 1187 only valid on intrinsic declarations and cannot be applied to a 1188 call site or arbitrary function. 1189 1190.. _gc: 1191 1192Garbage Collector Strategy Names 1193-------------------------------- 1194 1195Each function may specify a garbage collector strategy name, which is simply a 1196string: 1197 1198.. code-block:: llvm 1199 1200 define void @f() gc "name" { ... } 1201 1202The supported values of *name* includes those :ref:`built in to LLVM 1203<builtin-gc-strategies>` and any provided by loaded plugins. Specifying a GC 1204strategy will cause the compiler to alter its output in order to support the 1205named garbage collection algorithm. Note that LLVM itself does not contain a 1206garbage collector, this functionality is restricted to generating machine code 1207which can interoperate with a collector provided externally. 1208 1209.. _prefixdata: 1210 1211Prefix Data 1212----------- 1213 1214Prefix data is data associated with a function which the code 1215generator will emit immediately before the function's entrypoint. 1216The purpose of this feature is to allow frontends to associate 1217language-specific runtime metadata with specific functions and make it 1218available through the function pointer while still allowing the 1219function pointer to be called. 1220 1221To access the data for a given function, a program may bitcast the 1222function pointer to a pointer to the constant's type and dereference 1223index -1. This implies that the IR symbol points just past the end of 1224the prefix data. For instance, take the example of a function annotated 1225with a single ``i32``, 1226 1227.. code-block:: llvm 1228 1229 define void @f() prefix i32 123 { ... } 1230 1231The prefix data can be referenced as, 1232 1233.. code-block:: llvm 1234 1235 %0 = bitcast void* () @f to i32* 1236 %a = getelementptr inbounds i32, i32* %0, i32 -1 1237 %b = load i32, i32* %a 1238 1239Prefix data is laid out as if it were an initializer for a global variable 1240of the prefix data's type. The function will be placed such that the 1241beginning of the prefix data is aligned. This means that if the size 1242of the prefix data is not a multiple of the alignment size, the 1243function's entrypoint will not be aligned. If alignment of the 1244function's entrypoint is desired, padding must be added to the prefix 1245data. 1246 1247A function may have prefix data but no body. This has similar semantics 1248to the ``available_externally`` linkage in that the data may be used by the 1249optimizers but will not be emitted in the object file. 1250 1251.. _prologuedata: 1252 1253Prologue Data 1254------------- 1255 1256The ``prologue`` attribute allows arbitrary code (encoded as bytes) to 1257be inserted prior to the function body. This can be used for enabling 1258function hot-patching and instrumentation. 1259 1260To maintain the semantics of ordinary function calls, the prologue data must 1261have a particular format. Specifically, it must begin with a sequence of 1262bytes which decode to a sequence of machine instructions, valid for the 1263module's target, which transfer control to the point immediately succeeding 1264the prologue data, without performing any other visible action. This allows 1265the inliner and other passes to reason about the semantics of the function 1266definition without needing to reason about the prologue data. Obviously this 1267makes the format of the prologue data highly target dependent. 1268 1269A trivial example of valid prologue data for the x86 architecture is ``i8 144``, 1270which encodes the ``nop`` instruction: 1271 1272.. code-block:: text 1273 1274 define void @f() prologue i8 144 { ... } 1275 1276Generally prologue data can be formed by encoding a relative branch instruction 1277which skips the metadata, as in this example of valid prologue data for the 1278x86_64 architecture, where the first two bytes encode ``jmp .+10``: 1279 1280.. code-block:: text 1281 1282 %0 = type <{ i8, i8, i8* }> 1283 1284 define void @f() prologue %0 <{ i8 235, i8 8, i8* @md}> { ... } 1285 1286A function may have prologue data but no body. This has similar semantics 1287to the ``available_externally`` linkage in that the data may be used by the 1288optimizers but will not be emitted in the object file. 1289 1290.. _personalityfn: 1291 1292Personality Function 1293-------------------- 1294 1295The ``personality`` attribute permits functions to specify what function 1296to use for exception handling. 1297 1298.. _attrgrp: 1299 1300Attribute Groups 1301---------------- 1302 1303Attribute groups are groups of attributes that are referenced by objects within 1304the IR. They are important for keeping ``.ll`` files readable, because a lot of 1305functions will use the same set of attributes. In the degenerative case of a 1306``.ll`` file that corresponds to a single ``.c`` file, the single attribute 1307group will capture the important command line flags used to build that file. 1308 1309An attribute group is a module-level object. To use an attribute group, an 1310object references the attribute group's ID (e.g. ``#37``). An object may refer 1311to more than one attribute group. In that situation, the attributes from the 1312different groups are merged. 1313 1314Here is an example of attribute groups for a function that should always be 1315inlined, has a stack alignment of 4, and which shouldn't use SSE instructions: 1316 1317.. code-block:: llvm 1318 1319 ; Target-independent attributes: 1320 attributes #0 = { alwaysinline alignstack=4 } 1321 1322 ; Target-dependent attributes: 1323 attributes #1 = { "no-sse" } 1324 1325 ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse". 1326 define void @f() #0 #1 { ... } 1327 1328.. _fnattrs: 1329 1330Function Attributes 1331------------------- 1332 1333Function attributes are set to communicate additional information about 1334a function. Function attributes are considered to be part of the 1335function, not of the function type, so functions with different function 1336attributes can have the same function type. 1337 1338Function attributes are simple keywords that follow the type specified. 1339If multiple attributes are needed, they are space separated. For 1340example: 1341 1342.. code-block:: llvm 1343 1344 define void @f() noinline { ... } 1345 define void @f() alwaysinline { ... } 1346 define void @f() alwaysinline optsize { ... } 1347 define void @f() optsize { ... } 1348 1349``alignstack(<n>)`` 1350 This attribute indicates that, when emitting the prologue and 1351 epilogue, the backend should forcibly align the stack pointer. 1352 Specify the desired alignment, which must be a power of two, in 1353 parentheses. 1354``allocsize(<EltSizeParam>[, <NumEltsParam>])`` 1355 This attribute indicates that the annotated function will always return at 1356 least a given number of bytes (or null). Its arguments are zero-indexed 1357 parameter numbers; if one argument is provided, then it's assumed that at 1358 least ``CallSite.Args[EltSizeParam]`` bytes will be available at the 1359 returned pointer. If two are provided, then it's assumed that 1360 ``CallSite.Args[EltSizeParam] * CallSite.Args[NumEltsParam]`` bytes are 1361 available. The referenced parameters must be integer types. No assumptions 1362 are made about the contents of the returned block of memory. 1363``alwaysinline`` 1364 This attribute indicates that the inliner should attempt to inline 1365 this function into callers whenever possible, ignoring any active 1366 inlining size threshold for this caller. 1367``builtin`` 1368 This indicates that the callee function at a call site should be 1369 recognized as a built-in function, even though the function's declaration 1370 uses the ``nobuiltin`` attribute. This is only valid at call sites for 1371 direct calls to functions that are declared with the ``nobuiltin`` 1372 attribute. 1373``cold`` 1374 This attribute indicates that this function is rarely called. When 1375 computing edge weights, basic blocks post-dominated by a cold 1376 function call are also considered to be cold; and, thus, given low 1377 weight. 1378``convergent`` 1379 In some parallel execution models, there exist operations that cannot be 1380 made control-dependent on any additional values. We call such operations 1381 ``convergent``, and mark them with this attribute. 1382 1383 The ``convergent`` attribute may appear on functions or call/invoke 1384 instructions. When it appears on a function, it indicates that calls to 1385 this function should not be made control-dependent on additional values. 1386 For example, the intrinsic ``llvm.nvvm.barrier0`` is ``convergent``, so 1387 calls to this intrinsic cannot be made control-dependent on additional 1388 values. 1389 1390 When it appears on a call/invoke, the ``convergent`` attribute indicates 1391 that we should treat the call as though we're calling a convergent 1392 function. This is particularly useful on indirect calls; without this we 1393 may treat such calls as though the target is non-convergent. 1394 1395 The optimizer may remove the ``convergent`` attribute on functions when it 1396 can prove that the function does not execute any convergent operations. 1397 Similarly, the optimizer may remove ``convergent`` on calls/invokes when it 1398 can prove that the call/invoke cannot call a convergent function. 1399``inaccessiblememonly`` 1400 This attribute indicates that the function may only access memory that 1401 is not accessible by the module being compiled. This is a weaker form 1402 of ``readnone``. If the function reads or writes other memory, the 1403 behavior is undefined. 1404``inaccessiblemem_or_argmemonly`` 1405 This attribute indicates that the function may only access memory that is 1406 either not accessible by the module being compiled, or is pointed to 1407 by its pointer arguments. This is a weaker form of ``argmemonly``. If the 1408 function reads or writes other memory, the behavior is undefined. 1409``inlinehint`` 1410 This attribute indicates that the source code contained a hint that 1411 inlining this function is desirable (such as the "inline" keyword in 1412 C/C++). It is just a hint; it imposes no requirements on the 1413 inliner. 1414``jumptable`` 1415 This attribute indicates that the function should be added to a 1416 jump-instruction table at code-generation time, and that all address-taken 1417 references to this function should be replaced with a reference to the 1418 appropriate jump-instruction-table function pointer. Note that this creates 1419 a new pointer for the original function, which means that code that depends 1420 on function-pointer identity can break. So, any function annotated with 1421 ``jumptable`` must also be ``unnamed_addr``. 1422``minsize`` 1423 This attribute suggests that optimization passes and code generator 1424 passes make choices that keep the code size of this function as small 1425 as possible and perform optimizations that may sacrifice runtime 1426 performance in order to minimize the size of the generated code. 1427``naked`` 1428 This attribute disables prologue / epilogue emission for the 1429 function. This can have very system-specific consequences. 1430``no-jump-tables`` 1431 When this attribute is set to true, the jump tables and lookup tables that 1432 can be generated from a switch case lowering are disabled. 1433``nobuiltin`` 1434 This indicates that the callee function at a call site is not recognized as 1435 a built-in function. LLVM will retain the original call and not replace it 1436 with equivalent code based on the semantics of the built-in function, unless 1437 the call site uses the ``builtin`` attribute. This is valid at call sites 1438 and on function declarations and definitions. 1439``noduplicate`` 1440 This attribute indicates that calls to the function cannot be 1441 duplicated. A call to a ``noduplicate`` function may be moved 1442 within its parent function, but may not be duplicated within 1443 its parent function. 1444 1445 A function containing a ``noduplicate`` call may still 1446 be an inlining candidate, provided that the call is not 1447 duplicated by inlining. That implies that the function has 1448 internal linkage and only has one call site, so the original 1449 call is dead after inlining. 1450``noimplicitfloat`` 1451 This attributes disables implicit floating-point instructions. 1452``noinline`` 1453 This attribute indicates that the inliner should never inline this 1454 function in any situation. This attribute may not be used together 1455 with the ``alwaysinline`` attribute. 1456``nonlazybind`` 1457 This attribute suppresses lazy symbol binding for the function. This 1458 may make calls to the function faster, at the cost of extra program 1459 startup time if the function is not called during program startup. 1460``noredzone`` 1461 This attribute indicates that the code generator should not use a 1462 red zone, even if the target-specific ABI normally permits it. 1463``indirect-tls-seg-refs`` 1464 This attribute indicates that the code generator should not use 1465 direct TLS access through segment registers, even if the 1466 target-specific ABI normally permits it. 1467``noreturn`` 1468 This function attribute indicates that the function never returns 1469 normally. This produces undefined behavior at runtime if the 1470 function ever does dynamically return. 1471``norecurse`` 1472 This function attribute indicates that the function does not call itself 1473 either directly or indirectly down any possible call path. This produces 1474 undefined behavior at runtime if the function ever does recurse. 1475``nounwind`` 1476 This function attribute indicates that the function never raises an 1477 exception. If the function does raise an exception, its runtime 1478 behavior is undefined. However, functions marked nounwind may still 1479 trap or generate asynchronous exceptions. Exception handling schemes 1480 that are recognized by LLVM to handle asynchronous exceptions, such 1481 as SEH, will still provide their implementation defined semantics. 1482``"null-pointer-is-valid"`` 1483 If ``"null-pointer-is-valid"`` is set to ``"true"``, then ``null`` address 1484 in address-space 0 is considered to be a valid address for memory loads and 1485 stores. Any analysis or optimization should not treat dereferencing a 1486 pointer to ``null`` as undefined behavior in this function. 1487 Note: Comparing address of a global variable to ``null`` may still 1488 evaluate to false because of a limitation in querying this attribute inside 1489 constant expressions. 1490``optforfuzzing`` 1491 This attribute indicates that this function should be optimized 1492 for maximum fuzzing signal. 1493``optnone`` 1494 This function attribute indicates that most optimization passes will skip 1495 this function, with the exception of interprocedural optimization passes. 1496 Code generation defaults to the "fast" instruction selector. 1497 This attribute cannot be used together with the ``alwaysinline`` 1498 attribute; this attribute is also incompatible 1499 with the ``minsize`` attribute and the ``optsize`` attribute. 1500 1501 This attribute requires the ``noinline`` attribute to be specified on 1502 the function as well, so the function is never inlined into any caller. 1503 Only functions with the ``alwaysinline`` attribute are valid 1504 candidates for inlining into the body of this function. 1505``optsize`` 1506 This attribute suggests that optimization passes and code generator 1507 passes make choices that keep the code size of this function low, 1508 and otherwise do optimizations specifically to reduce code size as 1509 long as they do not significantly impact runtime performance. 1510``"patchable-function"`` 1511 This attribute tells the code generator that the code 1512 generated for this function needs to follow certain conventions that 1513 make it possible for a runtime function to patch over it later. 1514 The exact effect of this attribute depends on its string value, 1515 for which there currently is one legal possibility: 1516 1517 * ``"prologue-short-redirect"`` - This style of patchable 1518 function is intended to support patching a function prologue to 1519 redirect control away from the function in a thread safe 1520 manner. It guarantees that the first instruction of the 1521 function will be large enough to accommodate a short jump 1522 instruction, and will be sufficiently aligned to allow being 1523 fully changed via an atomic compare-and-swap instruction. 1524 While the first requirement can be satisfied by inserting large 1525 enough NOP, LLVM can and will try to re-purpose an existing 1526 instruction (i.e. one that would have to be emitted anyway) as 1527 the patchable instruction larger than a short jump. 1528 1529 ``"prologue-short-redirect"`` is currently only supported on 1530 x86-64. 1531 1532 This attribute by itself does not imply restrictions on 1533 inter-procedural optimizations. All of the semantic effects the 1534 patching may have to be separately conveyed via the linkage type. 1535``"probe-stack"`` 1536 This attribute indicates that the function will trigger a guard region 1537 in the end of the stack. It ensures that accesses to the stack must be 1538 no further apart than the size of the guard region to a previous 1539 access of the stack. It takes one required string value, the name of 1540 the stack probing function that will be called. 1541 1542 If a function that has a ``"probe-stack"`` attribute is inlined into 1543 a function with another ``"probe-stack"`` attribute, the resulting 1544 function has the ``"probe-stack"`` attribute of the caller. If a 1545 function that has a ``"probe-stack"`` attribute is inlined into a 1546 function that has no ``"probe-stack"`` attribute at all, the resulting 1547 function has the ``"probe-stack"`` attribute of the callee. 1548``readnone`` 1549 On a function, this attribute indicates that the function computes its 1550 result (or decides to unwind an exception) based strictly on its arguments, 1551 without dereferencing any pointer arguments or otherwise accessing 1552 any mutable state (e.g. memory, control registers, etc) visible to 1553 caller functions. It does not write through any pointer arguments 1554 (including ``byval`` arguments) and never changes any state visible 1555 to callers. This means while it cannot unwind exceptions by calling 1556 the ``C++`` exception throwing methods (since they write to memory), there may 1557 be non-``C++`` mechanisms that throw exceptions without writing to LLVM 1558 visible memory. 1559 1560 On an argument, this attribute indicates that the function does not 1561 dereference that pointer argument, even though it may read or write the 1562 memory that the pointer points to if accessed through other pointers. 1563 1564 If a readnone function reads or writes memory visible to the program, or 1565 has other side-effects, the behavior is undefined. If a function reads from 1566 or writes to a readnone pointer argument, the behavior is undefined. 1567``readonly`` 1568 On a function, this attribute indicates that the function does not write 1569 through any pointer arguments (including ``byval`` arguments) or otherwise 1570 modify any state (e.g. memory, control registers, etc) visible to 1571 caller functions. It may dereference pointer arguments and read 1572 state that may be set in the caller. A readonly function always 1573 returns the same value (or unwinds an exception identically) when 1574 called with the same set of arguments and global state. This means while it 1575 cannot unwind exceptions by calling the ``C++`` exception throwing methods 1576 (since they write to memory), there may be non-``C++`` mechanisms that throw 1577 exceptions without writing to LLVM visible memory. 1578 1579 On an argument, this attribute indicates that the function does not write 1580 through this pointer argument, even though it may write to the memory that 1581 the pointer points to. 1582 1583 If a readonly function writes memory visible to the program, or 1584 has other side-effects, the behavior is undefined. If a function writes to 1585 a readonly pointer argument, the behavior is undefined. 1586``"stack-probe-size"`` 1587 This attribute controls the behavior of stack probes: either 1588 the ``"probe-stack"`` attribute, or ABI-required stack probes, if any. 1589 It defines the size of the guard region. It ensures that if the function 1590 may use more stack space than the size of the guard region, stack probing 1591 sequence will be emitted. It takes one required integer value, which 1592 is 4096 by default. 1593 1594 If a function that has a ``"stack-probe-size"`` attribute is inlined into 1595 a function with another ``"stack-probe-size"`` attribute, the resulting 1596 function has the ``"stack-probe-size"`` attribute that has the lower 1597 numeric value. If a function that has a ``"stack-probe-size"`` attribute is 1598 inlined into a function that has no ``"stack-probe-size"`` attribute 1599 at all, the resulting function has the ``"stack-probe-size"`` attribute 1600 of the callee. 1601``"no-stack-arg-probe"`` 1602 This attribute disables ABI-required stack probes, if any. 1603``writeonly`` 1604 On a function, this attribute indicates that the function may write to but 1605 does not read from memory. 1606 1607 On an argument, this attribute indicates that the function may write to but 1608 does not read through this pointer argument (even though it may read from 1609 the memory that the pointer points to). 1610 1611 If a writeonly function reads memory visible to the program, or 1612 has other side-effects, the behavior is undefined. If a function reads 1613 from a writeonly pointer argument, the behavior is undefined. 1614``argmemonly`` 1615 This attribute indicates that the only memory accesses inside function are 1616 loads and stores from objects pointed to by its pointer-typed arguments, 1617 with arbitrary offsets. Or in other words, all memory operations in the 1618 function can refer to memory only using pointers based on its function 1619 arguments. 1620 1621 Note that ``argmemonly`` can be used together with ``readonly`` attribute 1622 in order to specify that function reads only from its arguments. 1623 1624 If an argmemonly function reads or writes memory other than the pointer 1625 arguments, or has other side-effects, the behavior is undefined. 1626``returns_twice`` 1627 This attribute indicates that this function can return twice. The C 1628 ``setjmp`` is an example of such a function. The compiler disables 1629 some optimizations (like tail calls) in the caller of these 1630 functions. 1631``safestack`` 1632 This attribute indicates that 1633 `SafeStack <http://clang.llvm.org/docs/SafeStack.html>`_ 1634 protection is enabled for this function. 1635 1636 If a function that has a ``safestack`` attribute is inlined into a 1637 function that doesn't have a ``safestack`` attribute or which has an 1638 ``ssp``, ``sspstrong`` or ``sspreq`` attribute, then the resulting 1639 function will have a ``safestack`` attribute. 1640``sanitize_address`` 1641 This attribute indicates that AddressSanitizer checks 1642 (dynamic address safety analysis) are enabled for this function. 1643``sanitize_memory`` 1644 This attribute indicates that MemorySanitizer checks (dynamic detection 1645 of accesses to uninitialized memory) are enabled for this function. 1646``sanitize_thread`` 1647 This attribute indicates that ThreadSanitizer checks 1648 (dynamic thread safety analysis) are enabled for this function. 1649``sanitize_hwaddress`` 1650 This attribute indicates that HWAddressSanitizer checks 1651 (dynamic address safety analysis based on tagged pointers) are enabled for 1652 this function. 1653``speculative_load_hardening`` 1654 This attribute indicates that 1655 `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_ 1656 should be enabled for the function body. 1657 1658 Speculative Load Hardening is a best-effort mitigation against 1659 information leak attacks that make use of control flow 1660 miss-speculation - specifically miss-speculation of whether a branch 1661 is taken or not. Typically vulnerabilities enabling such attacks are 1662 classified as "Spectre variant #1". Notably, this does not attempt to 1663 mitigate against miss-speculation of branch target, classified as 1664 "Spectre variant #2" vulnerabilities. 1665 1666 When inlining, the attribute is sticky. Inlining a function that carries 1667 this attribute will cause the caller to gain the attribute. This is intended 1668 to provide a maximally conservative model where the code in a function 1669 annotated with this attribute will always (even after inlining) end up 1670 hardened. 1671``speculatable`` 1672 This function attribute indicates that the function does not have any 1673 effects besides calculating its result and does not have undefined behavior. 1674 Note that ``speculatable`` is not enough to conclude that along any 1675 particular execution path the number of calls to this function will not be 1676 externally observable. This attribute is only valid on functions 1677 and declarations, not on individual call sites. If a function is 1678 incorrectly marked as speculatable and really does exhibit 1679 undefined behavior, the undefined behavior may be observed even 1680 if the call site is dead code. 1681 1682``ssp`` 1683 This attribute indicates that the function should emit a stack 1684 smashing protector. It is in the form of a "canary" --- a random value 1685 placed on the stack before the local variables that's checked upon 1686 return from the function to see if it has been overwritten. A 1687 heuristic is used to determine if a function needs stack protectors 1688 or not. The heuristic used will enable protectors for functions with: 1689 1690 - Character arrays larger than ``ssp-buffer-size`` (default 8). 1691 - Aggregates containing character arrays larger than ``ssp-buffer-size``. 1692 - Calls to alloca() with variable sizes or constant sizes greater than 1693 ``ssp-buffer-size``. 1694 1695 Variables that are identified as requiring a protector will be arranged 1696 on the stack such that they are adjacent to the stack protector guard. 1697 1698 If a function that has an ``ssp`` attribute is inlined into a 1699 function that doesn't have an ``ssp`` attribute, then the resulting 1700 function will have an ``ssp`` attribute. 1701``sspreq`` 1702 This attribute indicates that the function should *always* emit a 1703 stack smashing protector. This overrides the ``ssp`` function 1704 attribute. 1705 1706 Variables that are identified as requiring a protector will be arranged 1707 on the stack such that they are adjacent to the stack protector guard. 1708 The specific layout rules are: 1709 1710 #. Large arrays and structures containing large arrays 1711 (``>= ssp-buffer-size``) are closest to the stack protector. 1712 #. Small arrays and structures containing small arrays 1713 (``< ssp-buffer-size``) are 2nd closest to the protector. 1714 #. Variables that have had their address taken are 3rd closest to the 1715 protector. 1716 1717 If a function that has an ``sspreq`` attribute is inlined into a 1718 function that doesn't have an ``sspreq`` attribute or which has an 1719 ``ssp`` or ``sspstrong`` attribute, then the resulting function will have 1720 an ``sspreq`` attribute. 1721``sspstrong`` 1722 This attribute indicates that the function should emit a stack smashing 1723 protector. This attribute causes a strong heuristic to be used when 1724 determining if a function needs stack protectors. The strong heuristic 1725 will enable protectors for functions with: 1726 1727 - Arrays of any size and type 1728 - Aggregates containing an array of any size and type. 1729 - Calls to alloca(). 1730 - Local variables that have had their address taken. 1731 1732 Variables that are identified as requiring a protector will be arranged 1733 on the stack such that they are adjacent to the stack protector guard. 1734 The specific layout rules are: 1735 1736 #. Large arrays and structures containing large arrays 1737 (``>= ssp-buffer-size``) are closest to the stack protector. 1738 #. Small arrays and structures containing small arrays 1739 (``< ssp-buffer-size``) are 2nd closest to the protector. 1740 #. Variables that have had their address taken are 3rd closest to the 1741 protector. 1742 1743 This overrides the ``ssp`` function attribute. 1744 1745 If a function that has an ``sspstrong`` attribute is inlined into a 1746 function that doesn't have an ``sspstrong`` attribute, then the 1747 resulting function will have an ``sspstrong`` attribute. 1748``strictfp`` 1749 This attribute indicates that the function was called from a scope that 1750 requires strict floating-point semantics. LLVM will not attempt any 1751 optimizations that require assumptions about the floating-point rounding 1752 mode or that might alter the state of floating-point status flags that 1753 might otherwise be set or cleared by calling this function. 1754``"thunk"`` 1755 This attribute indicates that the function will delegate to some other 1756 function with a tail call. The prototype of a thunk should not be used for 1757 optimization purposes. The caller is expected to cast the thunk prototype to 1758 match the thunk target prototype. 1759``uwtable`` 1760 This attribute indicates that the ABI being targeted requires that 1761 an unwind table entry be produced for this function even if we can 1762 show that no exceptions passes by it. This is normally the case for 1763 the ELF x86-64 abi, but it can be disabled for some compilation 1764 units. 1765``nocf_check`` 1766 This attribute indicates that no control-flow check will be performed on 1767 the attributed entity. It disables -fcf-protection=<> for a specific 1768 entity to fine grain the HW control flow protection mechanism. The flag 1769 is target independent and currently appertains to a function or function 1770 pointer. 1771``shadowcallstack`` 1772 This attribute indicates that the ShadowCallStack checks are enabled for 1773 the function. The instrumentation checks that the return address for the 1774 function has not changed between the function prolog and eiplog. It is 1775 currently x86_64-specific. 1776 1777.. _glattrs: 1778 1779Global Attributes 1780----------------- 1781 1782Attributes may be set to communicate additional information about a global variable. 1783Unlike :ref:`function attributes <fnattrs>`, attributes on a global variable 1784are grouped into a single :ref:`attribute group <attrgrp>`. 1785 1786.. _opbundles: 1787 1788Operand Bundles 1789--------------- 1790 1791Operand bundles are tagged sets of SSA values that can be associated 1792with certain LLVM instructions (currently only ``call`` s and 1793``invoke`` s). In a way they are like metadata, but dropping them is 1794incorrect and will change program semantics. 1795 1796Syntax:: 1797 1798 operand bundle set ::= '[' operand bundle (, operand bundle )* ']' 1799 operand bundle ::= tag '(' [ bundle operand ] (, bundle operand )* ')' 1800 bundle operand ::= SSA value 1801 tag ::= string constant 1802 1803Operand bundles are **not** part of a function's signature, and a 1804given function may be called from multiple places with different kinds 1805of operand bundles. This reflects the fact that the operand bundles 1806are conceptually a part of the ``call`` (or ``invoke``), not the 1807callee being dispatched to. 1808 1809Operand bundles are a generic mechanism intended to support 1810runtime-introspection-like functionality for managed languages. While 1811the exact semantics of an operand bundle depend on the bundle tag, 1812there are certain limitations to how much the presence of an operand 1813bundle can influence the semantics of a program. These restrictions 1814are described as the semantics of an "unknown" operand bundle. As 1815long as the behavior of an operand bundle is describable within these 1816restrictions, LLVM does not need to have special knowledge of the 1817operand bundle to not miscompile programs containing it. 1818 1819- The bundle operands for an unknown operand bundle escape in unknown 1820 ways before control is transferred to the callee or invokee. 1821- Calls and invokes with operand bundles have unknown read / write 1822 effect on the heap on entry and exit (even if the call target is 1823 ``readnone`` or ``readonly``), unless they're overridden with 1824 callsite specific attributes. 1825- An operand bundle at a call site cannot change the implementation 1826 of the called function. Inter-procedural optimizations work as 1827 usual as long as they take into account the first two properties. 1828 1829More specific types of operand bundles are described below. 1830 1831.. _deopt_opbundles: 1832 1833Deoptimization Operand Bundles 1834^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1835 1836Deoptimization operand bundles are characterized by the ``"deopt"`` 1837operand bundle tag. These operand bundles represent an alternate 1838"safe" continuation for the call site they're attached to, and can be 1839used by a suitable runtime to deoptimize the compiled frame at the 1840specified call site. There can be at most one ``"deopt"`` operand 1841bundle attached to a call site. Exact details of deoptimization is 1842out of scope for the language reference, but it usually involves 1843rewriting a compiled frame into a set of interpreted frames. 1844 1845From the compiler's perspective, deoptimization operand bundles make 1846the call sites they're attached to at least ``readonly``. They read 1847through all of their pointer typed operands (even if they're not 1848otherwise escaped) and the entire visible heap. Deoptimization 1849operand bundles do not capture their operands except during 1850deoptimization, in which case control will not be returned to the 1851compiled frame. 1852 1853The inliner knows how to inline through calls that have deoptimization 1854operand bundles. Just like inlining through a normal call site 1855involves composing the normal and exceptional continuations, inlining 1856through a call site with a deoptimization operand bundle needs to 1857appropriately compose the "safe" deoptimization continuation. The 1858inliner does this by prepending the parent's deoptimization 1859continuation to every deoptimization continuation in the inlined body. 1860E.g. inlining ``@f`` into ``@g`` in the following example 1861 1862.. code-block:: llvm 1863 1864 define void @f() { 1865 call void @x() ;; no deopt state 1866 call void @y() [ "deopt"(i32 10) ] 1867 call void @y() [ "deopt"(i32 10), "unknown"(i8* null) ] 1868 ret void 1869 } 1870 1871 define void @g() { 1872 call void @f() [ "deopt"(i32 20) ] 1873 ret void 1874 } 1875 1876will result in 1877 1878.. code-block:: llvm 1879 1880 define void @g() { 1881 call void @x() ;; still no deopt state 1882 call void @y() [ "deopt"(i32 20, i32 10) ] 1883 call void @y() [ "deopt"(i32 20, i32 10), "unknown"(i8* null) ] 1884 ret void 1885 } 1886 1887It is the frontend's responsibility to structure or encode the 1888deoptimization state in a way that syntactically prepending the 1889caller's deoptimization state to the callee's deoptimization state is 1890semantically equivalent to composing the caller's deoptimization 1891continuation after the callee's deoptimization continuation. 1892 1893.. _ob_funclet: 1894 1895Funclet Operand Bundles 1896^^^^^^^^^^^^^^^^^^^^^^^ 1897 1898Funclet operand bundles are characterized by the ``"funclet"`` 1899operand bundle tag. These operand bundles indicate that a call site 1900is within a particular funclet. There can be at most one 1901``"funclet"`` operand bundle attached to a call site and it must have 1902exactly one bundle operand. 1903 1904If any funclet EH pads have been "entered" but not "exited" (per the 1905`description in the EH doc\ <ExceptionHandling.html#wineh-constraints>`_), 1906it is undefined behavior to execute a ``call`` or ``invoke`` which: 1907 1908* does not have a ``"funclet"`` bundle and is not a ``call`` to a nounwind 1909 intrinsic, or 1910* has a ``"funclet"`` bundle whose operand is not the most-recently-entered 1911 not-yet-exited funclet EH pad. 1912 1913Similarly, if no funclet EH pads have been entered-but-not-yet-exited, 1914executing a ``call`` or ``invoke`` with a ``"funclet"`` bundle is undefined behavior. 1915 1916GC Transition Operand Bundles 1917^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1918 1919GC transition operand bundles are characterized by the 1920``"gc-transition"`` operand bundle tag. These operand bundles mark a 1921call as a transition between a function with one GC strategy to a 1922function with a different GC strategy. If coordinating the transition 1923between GC strategies requires additional code generation at the call 1924site, these bundles may contain any values that are needed by the 1925generated code. For more details, see :ref:`GC Transitions 1926<gc_transition_args>`. 1927 1928.. _moduleasm: 1929 1930Module-Level Inline Assembly 1931---------------------------- 1932 1933Modules may contain "module-level inline asm" blocks, which corresponds 1934to the GCC "file scope inline asm" blocks. These blocks are internally 1935concatenated by LLVM and treated as a single unit, but may be separated 1936in the ``.ll`` file if desired. The syntax is very simple: 1937 1938.. code-block:: llvm 1939 1940 module asm "inline asm code goes here" 1941 module asm "more can go here" 1942 1943The strings can contain any character by escaping non-printable 1944characters. The escape sequence used is simply "\\xx" where "xx" is the 1945two digit hex code for the number. 1946 1947Note that the assembly string *must* be parseable by LLVM's integrated assembler 1948(unless it is disabled), even when emitting a ``.s`` file. 1949 1950.. _langref_datalayout: 1951 1952Data Layout 1953----------- 1954 1955A module may specify a target specific data layout string that specifies 1956how data is to be laid out in memory. The syntax for the data layout is 1957simply: 1958 1959.. code-block:: llvm 1960 1961 target datalayout = "layout specification" 1962 1963The *layout specification* consists of a list of specifications 1964separated by the minus sign character ('-'). Each specification starts 1965with a letter and may include other information after the letter to 1966define some aspect of the data layout. The specifications accepted are 1967as follows: 1968 1969``E`` 1970 Specifies that the target lays out data in big-endian form. That is, 1971 the bits with the most significance have the lowest address 1972 location. 1973``e`` 1974 Specifies that the target lays out data in little-endian form. That 1975 is, the bits with the least significance have the lowest address 1976 location. 1977``S<size>`` 1978 Specifies the natural alignment of the stack in bits. Alignment 1979 promotion of stack variables is limited to the natural stack 1980 alignment to avoid dynamic stack realignment. The stack alignment 1981 must be a multiple of 8-bits. If omitted, the natural stack 1982 alignment defaults to "unspecified", which does not prevent any 1983 alignment promotions. 1984``P<address space>`` 1985 Specifies the address space that corresponds to program memory. 1986 Harvard architectures can use this to specify what space LLVM 1987 should place things such as functions into. If omitted, the 1988 program memory space defaults to the default address space of 0, 1989 which corresponds to a Von Neumann architecture that has code 1990 and data in the same space. 1991``A<address space>`` 1992 Specifies the address space of objects created by '``alloca``'. 1993 Defaults to the default address space of 0. 1994``p[n]:<size>:<abi>:<pref>:<idx>`` 1995 This specifies the *size* of a pointer and its ``<abi>`` and 1996 ``<pref>``\erred alignments for address space ``n``. The fourth parameter 1997 ``<idx>`` is a size of index that used for address calculation. If not 1998 specified, the default index size is equal to the pointer size. All sizes 1999 are in bits. The address space, ``n``, is optional, and if not specified, 2000 denotes the default address space 0. The value of ``n`` must be 2001 in the range [1,2^23). 2002``i<size>:<abi>:<pref>`` 2003 This specifies the alignment for an integer type of a given bit 2004 ``<size>``. The value of ``<size>`` must be in the range [1,2^23). 2005``v<size>:<abi>:<pref>`` 2006 This specifies the alignment for a vector type of a given bit 2007 ``<size>``. 2008``f<size>:<abi>:<pref>`` 2009 This specifies the alignment for a floating-point type of a given bit 2010 ``<size>``. Only values of ``<size>`` that are supported by the target 2011 will work. 32 (float) and 64 (double) are supported on all targets; 80 2012 or 128 (different flavors of long double) are also supported on some 2013 targets. 2014``a:<abi>:<pref>`` 2015 This specifies the alignment for an object of aggregate type. 2016``F<type><abi>`` 2017 This specifies the alignment for function pointers. 2018 The options for ``<type>`` are: 2019 2020 * ``i``: The alignment of function pointers is independent of the alignment 2021 of functions, and is a multiple of ``<abi>``. 2022 * ``n``: The alignment of function pointers is a multiple of the explicit 2023 alignment specified on the function, and is a multiple of ``<abi>``. 2024``m:<mangling>`` 2025 If present, specifies that llvm names are mangled in the output. Symbols 2026 prefixed with the mangling escape character ``\01`` are passed through 2027 directly to the assembler without the escape character. The mangling style 2028 options are 2029 2030 * ``e``: ELF mangling: Private symbols get a ``.L`` prefix. 2031 * ``m``: Mips mangling: Private symbols get a ``$`` prefix. 2032 * ``o``: Mach-O mangling: Private symbols get ``L`` prefix. Other 2033 symbols get a ``_`` prefix. 2034 * ``x``: Windows x86 COFF mangling: Private symbols get the usual prefix. 2035 Regular C symbols get a ``_`` prefix. Functions with ``__stdcall``, 2036 ``__fastcall``, and ``__vectorcall`` have custom mangling that appends 2037 ``@N`` where N is the number of bytes used to pass parameters. C++ symbols 2038 starting with ``?`` are not mangled in any way. 2039 * ``w``: Windows COFF mangling: Similar to ``x``, except that normal C 2040 symbols do not receive a ``_`` prefix. 2041``n<size1>:<size2>:<size3>...`` 2042 This specifies a set of native integer widths for the target CPU in 2043 bits. For example, it might contain ``n32`` for 32-bit PowerPC, 2044 ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of 2045 this set are considered to support most general arithmetic operations 2046 efficiently. 2047``ni:<address space0>:<address space1>:<address space2>...`` 2048 This specifies pointer types with the specified address spaces 2049 as :ref:`Non-Integral Pointer Type <nointptrtype>` s. The ``0`` 2050 address space cannot be specified as non-integral. 2051 2052On every specification that takes a ``<abi>:<pref>``, specifying the 2053``<pref>`` alignment is optional. If omitted, the preceding ``:`` 2054should be omitted too and ``<pref>`` will be equal to ``<abi>``. 2055 2056When constructing the data layout for a given target, LLVM starts with a 2057default set of specifications which are then (possibly) overridden by 2058the specifications in the ``datalayout`` keyword. The default 2059specifications are given in this list: 2060 2061- ``E`` - big endian 2062- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment. 2063- ``p[n]:64:64:64`` - Other address spaces are assumed to be the 2064 same as the default address space. 2065- ``S0`` - natural stack alignment is unspecified 2066- ``i1:8:8`` - i1 is 8-bit (byte) aligned 2067- ``i8:8:8`` - i8 is 8-bit (byte) aligned 2068- ``i16:16:16`` - i16 is 16-bit aligned 2069- ``i32:32:32`` - i32 is 32-bit aligned 2070- ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred 2071 alignment of 64-bits 2072- ``f16:16:16`` - half is 16-bit aligned 2073- ``f32:32:32`` - float is 32-bit aligned 2074- ``f64:64:64`` - double is 64-bit aligned 2075- ``f128:128:128`` - quad is 128-bit aligned 2076- ``v64:64:64`` - 64-bit vector is 64-bit aligned 2077- ``v128:128:128`` - 128-bit vector is 128-bit aligned 2078- ``a:0:64`` - aggregates are 64-bit aligned 2079 2080When LLVM is determining the alignment for a given type, it uses the 2081following rules: 2082 2083#. If the type sought is an exact match for one of the specifications, 2084 that specification is used. 2085#. If no match is found, and the type sought is an integer type, then 2086 the smallest integer type that is larger than the bitwidth of the 2087 sought type is used. If none of the specifications are larger than 2088 the bitwidth then the largest integer type is used. For example, 2089 given the default specifications above, the i7 type will use the 2090 alignment of i8 (next largest) while both i65 and i256 will use the 2091 alignment of i64 (largest specified). 2092#. If no match is found, and the type sought is a vector type, then the 2093 largest vector type that is smaller than the sought vector type will 2094 be used as a fall back. This happens because <128 x double> can be 2095 implemented in terms of 64 <2 x double>, for example. 2096 2097The function of the data layout string may not be what you expect. 2098Notably, this is not a specification from the frontend of what alignment 2099the code generator should use. 2100 2101Instead, if specified, the target data layout is required to match what 2102the ultimate *code generator* expects. This string is used by the 2103mid-level optimizers to improve code, and this only works if it matches 2104what the ultimate code generator uses. There is no way to generate IR 2105that does not embed this target-specific detail into the IR. If you 2106don't specify the string, the default specifications will be used to 2107generate a Data Layout and the optimization phases will operate 2108accordingly and introduce target specificity into the IR with respect to 2109these default specifications. 2110 2111.. _langref_triple: 2112 2113Target Triple 2114------------- 2115 2116A module may specify a target triple string that describes the target 2117host. The syntax for the target triple is simply: 2118 2119.. code-block:: llvm 2120 2121 target triple = "x86_64-apple-macosx10.7.0" 2122 2123The *target triple* string consists of a series of identifiers delimited 2124by the minus sign character ('-'). The canonical forms are: 2125 2126:: 2127 2128 ARCHITECTURE-VENDOR-OPERATING_SYSTEM 2129 ARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT 2130 2131This information is passed along to the backend so that it generates 2132code for the proper architecture. It's possible to override this on the 2133command line with the ``-mtriple`` command line option. 2134 2135.. _pointeraliasing: 2136 2137Pointer Aliasing Rules 2138---------------------- 2139 2140Any memory access must be done through a pointer value associated with 2141an address range of the memory access, otherwise the behavior is 2142undefined. Pointer values are associated with address ranges according 2143to the following rules: 2144 2145- A pointer value is associated with the addresses associated with any 2146 value it is *based* on. 2147- An address of a global variable is associated with the address range 2148 of the variable's storage. 2149- The result value of an allocation instruction is associated with the 2150 address range of the allocated storage. 2151- A null pointer in the default address-space is associated with no 2152 address. 2153- An integer constant other than zero or a pointer value returned from 2154 a function not defined within LLVM may be associated with address 2155 ranges allocated through mechanisms other than those provided by 2156 LLVM. Such ranges shall not overlap with any ranges of addresses 2157 allocated by mechanisms provided by LLVM. 2158 2159A pointer value is *based* on another pointer value according to the 2160following rules: 2161 2162- A pointer value formed from a scalar ``getelementptr`` operation is *based* on 2163 the pointer-typed operand of the ``getelementptr``. 2164- The pointer in lane *l* of the result of a vector ``getelementptr`` operation 2165 is *based* on the pointer in lane *l* of the vector-of-pointers-typed operand 2166 of the ``getelementptr``. 2167- The result value of a ``bitcast`` is *based* on the operand of the 2168 ``bitcast``. 2169- A pointer value formed by an ``inttoptr`` is *based* on all pointer 2170 values that contribute (directly or indirectly) to the computation of 2171 the pointer's value. 2172- The "*based* on" relationship is transitive. 2173 2174Note that this definition of *"based"* is intentionally similar to the 2175definition of *"based"* in C99, though it is slightly weaker. 2176 2177LLVM IR does not associate types with memory. The result type of a 2178``load`` merely indicates the size and alignment of the memory from 2179which to load, as well as the interpretation of the value. The first 2180operand type of a ``store`` similarly only indicates the size and 2181alignment of the store. 2182 2183Consequently, type-based alias analysis, aka TBAA, aka 2184``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR. 2185:ref:`Metadata <metadata>` may be used to encode additional information 2186which specialized optimization passes may use to implement type-based 2187alias analysis. 2188 2189.. _volatile: 2190 2191Volatile Memory Accesses 2192------------------------ 2193 2194Certain memory accesses, such as :ref:`load <i_load>`'s, 2195:ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be 2196marked ``volatile``. The optimizers must not change the number of 2197volatile operations or change their order of execution relative to other 2198volatile operations. The optimizers *may* change the order of volatile 2199operations relative to non-volatile operations. This is not Java's 2200"volatile" and has no cross-thread synchronization behavior. 2201 2202A volatile load or store may have additional target-specific semantics. 2203Any volatile operation can have side effects, and any volatile operation 2204can read and/or modify state which is not accessible via a regular load 2205or store in this module. Volatile operations may use addresses which do 2206not point to memory (like MMIO registers). This means the compiler may 2207not use a volatile operation to prove a non-volatile access to that 2208address has defined behavior. 2209 2210The allowed side-effects for volatile accesses are limited. If a 2211non-volatile store to a given address would be legal, a volatile 2212operation may modify the memory at that address. A volatile operation 2213may not modify any other memory accessible by the module being compiled. 2214A volatile operation may not call any code in the current module. 2215 2216The compiler may assume execution will continue after a volatile operation, 2217so operations which modify memory or may have undefined behavior can be 2218hoisted past a volatile operation. 2219 2220IR-level volatile loads and stores cannot safely be optimized into 2221llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are 2222flagged volatile. Likewise, the backend should never split or merge 2223target-legal volatile load/store instructions. 2224 2225.. admonition:: Rationale 2226 2227 Platforms may rely on volatile loads and stores of natively supported 2228 data width to be executed as single instruction. For example, in C 2229 this holds for an l-value of volatile primitive type with native 2230 hardware support, but not necessarily for aggregate types. The 2231 frontend upholds these expectations, which are intentionally 2232 unspecified in the IR. The rules above ensure that IR transformations 2233 do not violate the frontend's contract with the language. 2234 2235.. _memmodel: 2236 2237Memory Model for Concurrent Operations 2238-------------------------------------- 2239 2240The LLVM IR does not define any way to start parallel threads of 2241execution or to register signal handlers. Nonetheless, there are 2242platform-specific ways to create them, and we define LLVM IR's behavior 2243in their presence. This model is inspired by the C++0x memory model. 2244 2245For a more informal introduction to this model, see the :doc:`Atomics`. 2246 2247We define a *happens-before* partial order as the least partial order 2248that 2249 2250- Is a superset of single-thread program order, and 2251- When a *synchronizes-with* ``b``, includes an edge from ``a`` to 2252 ``b``. *Synchronizes-with* pairs are introduced by platform-specific 2253 techniques, like pthread locks, thread creation, thread joining, 2254 etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering 2255 Constraints <ordering>`). 2256 2257Note that program order does not introduce *happens-before* edges 2258between a thread and signals executing inside that thread. 2259 2260Every (defined) read operation (load instructions, memcpy, atomic 2261loads/read-modify-writes, etc.) R reads a series of bytes written by 2262(defined) write operations (store instructions, atomic 2263stores/read-modify-writes, memcpy, etc.). For the purposes of this 2264section, initialized globals are considered to have a write of the 2265initializer which is atomic and happens before any other read or write 2266of the memory in question. For each byte of a read R, R\ :sub:`byte` 2267may see any write to the same byte, except: 2268 2269- If write\ :sub:`1` happens before write\ :sub:`2`, and 2270 write\ :sub:`2` happens before R\ :sub:`byte`, then 2271 R\ :sub:`byte` does not see write\ :sub:`1`. 2272- If R\ :sub:`byte` happens before write\ :sub:`3`, then 2273 R\ :sub:`byte` does not see write\ :sub:`3`. 2274 2275Given that definition, R\ :sub:`byte` is defined as follows: 2276 2277- If R is volatile, the result is target-dependent. (Volatile is 2278 supposed to give guarantees which can support ``sig_atomic_t`` in 2279 C/C++, and may be used for accesses to addresses that do not behave 2280 like normal memory. It does not generally provide cross-thread 2281 synchronization.) 2282- Otherwise, if there is no write to the same byte that happens before 2283 R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte. 2284- Otherwise, if R\ :sub:`byte` may see exactly one write, 2285 R\ :sub:`byte` returns the value written by that write. 2286- Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may 2287 see are atomic, it chooses one of the values written. See the :ref:`Atomic 2288 Memory Ordering Constraints <ordering>` section for additional 2289 constraints on how the choice is made. 2290- Otherwise R\ :sub:`byte` returns ``undef``. 2291 2292R returns the value composed of the series of bytes it read. This 2293implies that some bytes within the value may be ``undef`` **without** 2294the entire value being ``undef``. Note that this only defines the 2295semantics of the operation; it doesn't mean that targets will emit more 2296than one instruction to read the series of bytes. 2297 2298Note that in cases where none of the atomic intrinsics are used, this 2299model places only one restriction on IR transformations on top of what 2300is required for single-threaded execution: introducing a store to a byte 2301which might not otherwise be stored is not allowed in general. 2302(Specifically, in the case where another thread might write to and read 2303from an address, introducing a store can change a load that may see 2304exactly one write into a load that may see multiple writes.) 2305 2306.. _ordering: 2307 2308Atomic Memory Ordering Constraints 2309---------------------------------- 2310 2311Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`, 2312:ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`, 2313:ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take 2314ordering parameters that determine which other atomic instructions on 2315the same address they *synchronize with*. These semantics are borrowed 2316from Java and C++0x, but are somewhat more colloquial. If these 2317descriptions aren't precise enough, check those specs (see spec 2318references in the :doc:`atomics guide <Atomics>`). 2319:ref:`fence <i_fence>` instructions treat these orderings somewhat 2320differently since they don't take an address. See that instruction's 2321documentation for details. 2322 2323For a simpler introduction to the ordering constraints, see the 2324:doc:`Atomics`. 2325 2326``unordered`` 2327 The set of values that can be read is governed by the happens-before 2328 partial order. A value cannot be read unless some operation wrote 2329 it. This is intended to provide a guarantee strong enough to model 2330 Java's non-volatile shared variables. This ordering cannot be 2331 specified for read-modify-write operations; it is not strong enough 2332 to make them atomic in any interesting way. 2333``monotonic`` 2334 In addition to the guarantees of ``unordered``, there is a single 2335 total order for modifications by ``monotonic`` operations on each 2336 address. All modification orders must be compatible with the 2337 happens-before order. There is no guarantee that the modification 2338 orders can be combined to a global total order for the whole program 2339 (and this often will not be possible). The read in an atomic 2340 read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and 2341 :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification 2342 order immediately before the value it writes. If one atomic read 2343 happens before another atomic read of the same address, the later 2344 read must see the same value or a later value in the address's 2345 modification order. This disallows reordering of ``monotonic`` (or 2346 stronger) operations on the same address. If an address is written 2347 ``monotonic``-ally by one thread, and other threads ``monotonic``-ally 2348 read that address repeatedly, the other threads must eventually see 2349 the write. This corresponds to the C++0x/C1x 2350 ``memory_order_relaxed``. 2351``acquire`` 2352 In addition to the guarantees of ``monotonic``, a 2353 *synchronizes-with* edge may be formed with a ``release`` operation. 2354 This is intended to model C++'s ``memory_order_acquire``. 2355``release`` 2356 In addition to the guarantees of ``monotonic``, if this operation 2357 writes a value which is subsequently read by an ``acquire`` 2358 operation, it *synchronizes-with* that operation. (This isn't a 2359 complete description; see the C++0x definition of a release 2360 sequence.) This corresponds to the C++0x/C1x 2361 ``memory_order_release``. 2362``acq_rel`` (acquire+release) 2363 Acts as both an ``acquire`` and ``release`` operation on its 2364 address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``. 2365``seq_cst`` (sequentially consistent) 2366 In addition to the guarantees of ``acq_rel`` (``acquire`` for an 2367 operation that only reads, ``release`` for an operation that only 2368 writes), there is a global total order on all 2369 sequentially-consistent operations on all addresses, which is 2370 consistent with the *happens-before* partial order and with the 2371 modification orders of all the affected addresses. Each 2372 sequentially-consistent read sees the last preceding write to the 2373 same address in this global order. This corresponds to the C++0x/C1x 2374 ``memory_order_seq_cst`` and Java volatile. 2375 2376.. _syncscope: 2377 2378If an atomic operation is marked ``syncscope("singlethread")``, it only 2379*synchronizes with* and only participates in the seq\_cst total orderings of 2380other operations running in the same thread (for example, in signal handlers). 2381 2382If an atomic operation is marked ``syncscope("<target-scope>")``, where 2383``<target-scope>`` is a target specific synchronization scope, then it is target 2384dependent if it *synchronizes with* and participates in the seq\_cst total 2385orderings of other operations. 2386 2387Otherwise, an atomic operation that is not marked ``syncscope("singlethread")`` 2388or ``syncscope("<target-scope>")`` *synchronizes with* and participates in the 2389seq\_cst total orderings of other operations that are not marked 2390``syncscope("singlethread")`` or ``syncscope("<target-scope>")``. 2391 2392.. _floatenv: 2393 2394Floating-Point Environment 2395-------------------------- 2396 2397The default LLVM floating-point environment assumes that floating-point 2398instructions do not have side effects. Results assume the round-to-nearest 2399rounding mode. No floating-point exception state is maintained in this 2400environment. Therefore, there is no attempt to create or preserve invalid 2401operation (SNaN) or division-by-zero exceptions. 2402 2403The benefit of this exception-free assumption is that floating-point 2404operations may be speculated freely without any other fast-math relaxations 2405to the floating-point model. 2406 2407Code that requires different behavior than this should use the 2408:ref:`Constrained Floating-Point Intrinsics <constrainedfp>`. 2409 2410.. _fastmath: 2411 2412Fast-Math Flags 2413--------------- 2414 2415LLVM IR floating-point operations (:ref:`fadd <i_fadd>`, 2416:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`, 2417:ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`) and :ref:`call <i_call>` 2418may use the following flags to enable otherwise unsafe 2419floating-point transformations. 2420 2421``nnan`` 2422 No NaNs - Allow optimizations to assume the arguments and result are not 2423 NaN. If an argument is a nan, or the result would be a nan, it produces 2424 a :ref:`poison value <poisonvalues>` instead. 2425 2426``ninf`` 2427 No Infs - Allow optimizations to assume the arguments and result are not 2428 +/-Inf. If an argument is +/-Inf, or the result would be +/-Inf, it 2429 produces a :ref:`poison value <poisonvalues>` instead. 2430 2431``nsz`` 2432 No Signed Zeros - Allow optimizations to treat the sign of a zero 2433 argument or result as insignificant. 2434 2435``arcp`` 2436 Allow Reciprocal - Allow optimizations to use the reciprocal of an 2437 argument rather than perform division. 2438 2439``contract`` 2440 Allow floating-point contraction (e.g. fusing a multiply followed by an 2441 addition into a fused multiply-and-add). 2442 2443``afn`` 2444 Approximate functions - Allow substitution of approximate calculations for 2445 functions (sin, log, sqrt, etc). See floating-point intrinsic definitions 2446 for places where this can apply to LLVM's intrinsic math functions. 2447 2448``reassoc`` 2449 Allow reassociation transformations for floating-point instructions. 2450 This may dramatically change results in floating-point. 2451 2452``fast`` 2453 This flag implies all of the others. 2454 2455.. _uselistorder: 2456 2457Use-list Order Directives 2458------------------------- 2459 2460Use-list directives encode the in-memory order of each use-list, allowing the 2461order to be recreated. ``<order-indexes>`` is a comma-separated list of 2462indexes that are assigned to the referenced value's uses. The referenced 2463value's use-list is immediately sorted by these indexes. 2464 2465Use-list directives may appear at function scope or global scope. They are not 2466instructions, and have no effect on the semantics of the IR. When they're at 2467function scope, they must appear after the terminator of the final basic block. 2468 2469If basic blocks have their address taken via ``blockaddress()`` expressions, 2470``uselistorder_bb`` can be used to reorder their use-lists from outside their 2471function's scope. 2472 2473:Syntax: 2474 2475:: 2476 2477 uselistorder <ty> <value>, { <order-indexes> } 2478 uselistorder_bb @function, %block { <order-indexes> } 2479 2480:Examples: 2481 2482:: 2483 2484 define void @foo(i32 %arg1, i32 %arg2) { 2485 entry: 2486 ; ... instructions ... 2487 bb: 2488 ; ... instructions ... 2489 2490 ; At function scope. 2491 uselistorder i32 %arg1, { 1, 0, 2 } 2492 uselistorder label %bb, { 1, 0 } 2493 } 2494 2495 ; At global scope. 2496 uselistorder i32* @global, { 1, 2, 0 } 2497 uselistorder i32 7, { 1, 0 } 2498 uselistorder i32 (i32) @bar, { 1, 0 } 2499 uselistorder_bb @foo, %bb, { 5, 1, 3, 2, 0, 4 } 2500 2501.. _source_filename: 2502 2503Source Filename 2504--------------- 2505 2506The *source filename* string is set to the original module identifier, 2507which will be the name of the compiled source file when compiling from 2508source through the clang front end, for example. It is then preserved through 2509the IR and bitcode. 2510 2511This is currently necessary to generate a consistent unique global 2512identifier for local functions used in profile data, which prepends the 2513source file name to the local function name. 2514 2515The syntax for the source file name is simply: 2516 2517.. code-block:: text 2518 2519 source_filename = "/path/to/source.c" 2520 2521.. _typesystem: 2522 2523Type System 2524=========== 2525 2526The LLVM type system is one of the most important features of the 2527intermediate representation. Being typed enables a number of 2528optimizations to be performed on the intermediate representation 2529directly, without having to do extra analyses on the side before the 2530transformation. A strong type system makes it easier to read the 2531generated code and enables novel analyses and transformations that are 2532not feasible to perform on normal three address code representations. 2533 2534.. _t_void: 2535 2536Void Type 2537--------- 2538 2539:Overview: 2540 2541 2542The void type does not represent any value and has no size. 2543 2544:Syntax: 2545 2546 2547:: 2548 2549 void 2550 2551 2552.. _t_function: 2553 2554Function Type 2555------------- 2556 2557:Overview: 2558 2559 2560The function type can be thought of as a function signature. It consists of a 2561return type and a list of formal parameter types. The return type of a function 2562type is a void type or first class type --- except for :ref:`label <t_label>` 2563and :ref:`metadata <t_metadata>` types. 2564 2565:Syntax: 2566 2567:: 2568 2569 <returntype> (<parameter list>) 2570 2571...where '``<parameter list>``' is a comma-separated list of type 2572specifiers. Optionally, the parameter list may include a type ``...``, which 2573indicates that the function takes a variable number of arguments. Variable 2574argument functions can access their arguments with the :ref:`variable argument 2575handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type 2576except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`. 2577 2578:Examples: 2579 2580+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2581| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` | 2582+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2583| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. | 2584+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2585| ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. | 2586+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2587| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values | 2588+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2589 2590.. _t_firstclass: 2591 2592First Class Types 2593----------------- 2594 2595The :ref:`first class <t_firstclass>` types are perhaps the most important. 2596Values of these types are the only ones which can be produced by 2597instructions. 2598 2599.. _t_single_value: 2600 2601Single Value Types 2602^^^^^^^^^^^^^^^^^^ 2603 2604These are the types that are valid in registers from CodeGen's perspective. 2605 2606.. _t_integer: 2607 2608Integer Type 2609"""""""""""" 2610 2611:Overview: 2612 2613The integer type is a very simple type that simply specifies an 2614arbitrary bit width for the integer type desired. Any bit width from 1 2615bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified. 2616 2617:Syntax: 2618 2619:: 2620 2621 iN 2622 2623The number of bits the integer will occupy is specified by the ``N`` 2624value. 2625 2626Examples: 2627********* 2628 2629+----------------+------------------------------------------------+ 2630| ``i1`` | a single-bit integer. | 2631+----------------+------------------------------------------------+ 2632| ``i32`` | a 32-bit integer. | 2633+----------------+------------------------------------------------+ 2634| ``i1942652`` | a really big integer of over 1 million bits. | 2635+----------------+------------------------------------------------+ 2636 2637.. _t_floating: 2638 2639Floating-Point Types 2640"""""""""""""""""""" 2641 2642.. list-table:: 2643 :header-rows: 1 2644 2645 * - Type 2646 - Description 2647 2648 * - ``half`` 2649 - 16-bit floating-point value 2650 2651 * - ``float`` 2652 - 32-bit floating-point value 2653 2654 * - ``double`` 2655 - 64-bit floating-point value 2656 2657 * - ``fp128`` 2658 - 128-bit floating-point value (112-bit mantissa) 2659 2660 * - ``x86_fp80`` 2661 - 80-bit floating-point value (X87) 2662 2663 * - ``ppc_fp128`` 2664 - 128-bit floating-point value (two 64-bits) 2665 2666The binary format of half, float, double, and fp128 correspond to the 2667IEEE-754-2008 specifications for binary16, binary32, binary64, and binary128 2668respectively. 2669 2670X86_mmx Type 2671"""""""""""" 2672 2673:Overview: 2674 2675The x86_mmx type represents a value held in an MMX register on an x86 2676machine. The operations allowed on it are quite limited: parameters and 2677return values, load and store, and bitcast. User-specified MMX 2678instructions are represented as intrinsic or asm calls with arguments 2679and/or results of this type. There are no arrays, vectors or constants 2680of this type. 2681 2682:Syntax: 2683 2684:: 2685 2686 x86_mmx 2687 2688 2689.. _t_pointer: 2690 2691Pointer Type 2692"""""""""""" 2693 2694:Overview: 2695 2696The pointer type is used to specify memory locations. Pointers are 2697commonly used to reference objects in memory. 2698 2699Pointer types may have an optional address space attribute defining the 2700numbered address space where the pointed-to object resides. The default 2701address space is number zero. The semantics of non-zero address spaces 2702are target-specific. 2703 2704Note that LLVM does not permit pointers to void (``void*``) nor does it 2705permit pointers to labels (``label*``). Use ``i8*`` instead. 2706 2707:Syntax: 2708 2709:: 2710 2711 <type> * 2712 2713:Examples: 2714 2715+-------------------------+--------------------------------------------------------------------------------------------------------------+ 2716| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. | 2717+-------------------------+--------------------------------------------------------------------------------------------------------------+ 2718| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. | 2719+-------------------------+--------------------------------------------------------------------------------------------------------------+ 2720| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. | 2721+-------------------------+--------------------------------------------------------------------------------------------------------------+ 2722 2723.. _t_vector: 2724 2725Vector Type 2726""""""""""" 2727 2728:Overview: 2729 2730A vector type is a simple derived type that represents a vector of 2731elements. Vector types are used when multiple primitive data are 2732operated in parallel using a single instruction (SIMD). A vector type 2733requires a size (number of elements) and an underlying primitive data 2734type. Vector types are considered :ref:`first class <t_firstclass>`. 2735 2736:Syntax: 2737 2738:: 2739 2740 < <# elements> x <elementtype> > 2741 2742The number of elements is a constant integer value larger than 0; 2743elementtype may be any integer, floating-point or pointer type. Vectors 2744of size zero are not allowed. 2745 2746:Examples: 2747 2748+-------------------+--------------------------------------------------+ 2749| ``<4 x i32>`` | Vector of 4 32-bit integer values. | 2750+-------------------+--------------------------------------------------+ 2751| ``<8 x float>`` | Vector of 8 32-bit floating-point values. | 2752+-------------------+--------------------------------------------------+ 2753| ``<2 x i64>`` | Vector of 2 64-bit integer values. | 2754+-------------------+--------------------------------------------------+ 2755| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. | 2756+-------------------+--------------------------------------------------+ 2757 2758.. _t_label: 2759 2760Label Type 2761^^^^^^^^^^ 2762 2763:Overview: 2764 2765The label type represents code labels. 2766 2767:Syntax: 2768 2769:: 2770 2771 label 2772 2773.. _t_token: 2774 2775Token Type 2776^^^^^^^^^^ 2777 2778:Overview: 2779 2780The token type is used when a value is associated with an instruction 2781but all uses of the value must not attempt to introspect or obscure it. 2782As such, it is not appropriate to have a :ref:`phi <i_phi>` or 2783:ref:`select <i_select>` of type token. 2784 2785:Syntax: 2786 2787:: 2788 2789 token 2790 2791 2792 2793.. _t_metadata: 2794 2795Metadata Type 2796^^^^^^^^^^^^^ 2797 2798:Overview: 2799 2800The metadata type represents embedded metadata. No derived types may be 2801created from metadata except for :ref:`function <t_function>` arguments. 2802 2803:Syntax: 2804 2805:: 2806 2807 metadata 2808 2809.. _t_aggregate: 2810 2811Aggregate Types 2812^^^^^^^^^^^^^^^ 2813 2814Aggregate Types are a subset of derived types that can contain multiple 2815member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are 2816aggregate types. :ref:`Vectors <t_vector>` are not considered to be 2817aggregate types. 2818 2819.. _t_array: 2820 2821Array Type 2822"""""""""" 2823 2824:Overview: 2825 2826The array type is a very simple derived type that arranges elements 2827sequentially in memory. The array type requires a size (number of 2828elements) and an underlying data type. 2829 2830:Syntax: 2831 2832:: 2833 2834 [<# elements> x <elementtype>] 2835 2836The number of elements is a constant integer value; ``elementtype`` may 2837be any type with a size. 2838 2839:Examples: 2840 2841+------------------+--------------------------------------+ 2842| ``[40 x i32]`` | Array of 40 32-bit integer values. | 2843+------------------+--------------------------------------+ 2844| ``[41 x i32]`` | Array of 41 32-bit integer values. | 2845+------------------+--------------------------------------+ 2846| ``[4 x i8]`` | Array of 4 8-bit integer values. | 2847+------------------+--------------------------------------+ 2848 2849Here are some examples of multidimensional arrays: 2850 2851+-----------------------------+----------------------------------------------------------+ 2852| ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. | 2853+-----------------------------+----------------------------------------------------------+ 2854| ``[12 x [10 x float]]`` | 12x10 array of single precision floating-point values. | 2855+-----------------------------+----------------------------------------------------------+ 2856| ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. | 2857+-----------------------------+----------------------------------------------------------+ 2858 2859There is no restriction on indexing beyond the end of the array implied 2860by a static type (though there are restrictions on indexing beyond the 2861bounds of an allocated object in some cases). This means that 2862single-dimension 'variable sized array' addressing can be implemented in 2863LLVM with a zero length array type. An implementation of 'pascal style 2864arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for 2865example. 2866 2867.. _t_struct: 2868 2869Structure Type 2870"""""""""""""" 2871 2872:Overview: 2873 2874The structure type is used to represent a collection of data members 2875together in memory. The elements of a structure may be any type that has 2876a size. 2877 2878Structures in memory are accessed using '``load``' and '``store``' by 2879getting a pointer to a field with the '``getelementptr``' instruction. 2880Structures in registers are accessed using the '``extractvalue``' and 2881'``insertvalue``' instructions. 2882 2883Structures may optionally be "packed" structures, which indicate that 2884the alignment of the struct is one byte, and that there is no padding 2885between the elements. In non-packed structs, padding between field types 2886is inserted as defined by the DataLayout string in the module, which is 2887required to match what the underlying code generator expects. 2888 2889Structures can either be "literal" or "identified". A literal structure 2890is defined inline with other types (e.g. ``{i32, i32}*``) whereas 2891identified types are always defined at the top level with a name. 2892Literal types are uniqued by their contents and can never be recursive 2893or opaque since there is no way to write one. Identified types can be 2894recursive, can be opaqued, and are never uniqued. 2895 2896:Syntax: 2897 2898:: 2899 2900 %T1 = type { <type list> } ; Identified normal struct type 2901 %T2 = type <{ <type list> }> ; Identified packed struct type 2902 2903:Examples: 2904 2905+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2906| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values | 2907+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2908| ``{ float, i32 (i32) * }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32``, returning an ``i32``. | 2909+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2910| ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. | 2911+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 2912 2913.. _t_opaque: 2914 2915Opaque Structure Types 2916"""""""""""""""""""""" 2917 2918:Overview: 2919 2920Opaque structure types are used to represent named structure types that 2921do not have a body specified. This corresponds (for example) to the C 2922notion of a forward declared structure. 2923 2924:Syntax: 2925 2926:: 2927 2928 %X = type opaque 2929 %52 = type opaque 2930 2931:Examples: 2932 2933+--------------+-------------------+ 2934| ``opaque`` | An opaque type. | 2935+--------------+-------------------+ 2936 2937.. _constants: 2938 2939Constants 2940========= 2941 2942LLVM has several different basic types of constants. This section 2943describes them all and their syntax. 2944 2945Simple Constants 2946---------------- 2947 2948**Boolean constants** 2949 The two strings '``true``' and '``false``' are both valid constants 2950 of the ``i1`` type. 2951**Integer constants** 2952 Standard integers (such as '4') are constants of the 2953 :ref:`integer <t_integer>` type. Negative numbers may be used with 2954 integer types. 2955**Floating-point constants** 2956 Floating-point constants use standard decimal notation (e.g. 2957 123.421), exponential notation (e.g. 1.23421e+2), or a more precise 2958 hexadecimal notation (see below). The assembler requires the exact 2959 decimal value of a floating-point constant. For example, the 2960 assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating 2961 decimal in binary. Floating-point constants must have a 2962 :ref:`floating-point <t_floating>` type. 2963**Null pointer constants** 2964 The identifier '``null``' is recognized as a null pointer constant 2965 and must be of :ref:`pointer type <t_pointer>`. 2966**Token constants** 2967 The identifier '``none``' is recognized as an empty token constant 2968 and must be of :ref:`token type <t_token>`. 2969 2970The one non-intuitive notation for constants is the hexadecimal form of 2971floating-point constants. For example, the form 2972'``double 0x432ff973cafa8000``' is equivalent to (but harder to read 2973than) '``double 4.5e+15``'. The only time hexadecimal floating-point 2974constants are required (and the only time that they are generated by the 2975disassembler) is when a floating-point constant must be emitted but it 2976cannot be represented as a decimal floating-point number in a reasonable 2977number of digits. For example, NaN's, infinities, and other special 2978values are represented in their IEEE hexadecimal format so that assembly 2979and disassembly do not cause any bits to change in the constants. 2980 2981When using the hexadecimal form, constants of types half, float, and 2982double are represented using the 16-digit form shown above (which 2983matches the IEEE754 representation for double); half and float values 2984must, however, be exactly representable as IEEE 754 half and single 2985precision, respectively. Hexadecimal format is always used for long 2986double, and there are three forms of long double. The 80-bit format used 2987by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The 2988128-bit format used by PowerPC (two adjacent doubles) is represented by 2989``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is 2990represented by ``0xL`` followed by 32 hexadecimal digits. Long doubles 2991will only work if they match the long double format on your target. 2992The IEEE 16-bit format (half precision) is represented by ``0xH`` 2993followed by 4 hexadecimal digits. All hexadecimal formats are big-endian 2994(sign bit at the left). 2995 2996There are no constants of type x86_mmx. 2997 2998.. _complexconstants: 2999 3000Complex Constants 3001----------------- 3002 3003Complex constants are a (potentially recursive) combination of simple 3004constants and smaller complex constants. 3005 3006**Structure constants** 3007 Structure constants are represented with notation similar to 3008 structure type definitions (a comma separated list of elements, 3009 surrounded by braces (``{}``)). For example: 3010 "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as 3011 "``@G = external global i32``". Structure constants must have 3012 :ref:`structure type <t_struct>`, and the number and types of elements 3013 must match those specified by the type. 3014**Array constants** 3015 Array constants are represented with notation similar to array type 3016 definitions (a comma separated list of elements, surrounded by 3017 square brackets (``[]``)). For example: 3018 "``[ i32 42, i32 11, i32 74 ]``". Array constants must have 3019 :ref:`array type <t_array>`, and the number and types of elements must 3020 match those specified by the type. As a special case, character array 3021 constants may also be represented as a double-quoted string using the ``c`` 3022 prefix. For example: "``c"Hello World\0A\00"``". 3023**Vector constants** 3024 Vector constants are represented with notation similar to vector 3025 type definitions (a comma separated list of elements, surrounded by 3026 less-than/greater-than's (``<>``)). For example: 3027 "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants 3028 must have :ref:`vector type <t_vector>`, and the number and types of 3029 elements must match those specified by the type. 3030**Zero initialization** 3031 The string '``zeroinitializer``' can be used to zero initialize a 3032 value to zero of *any* type, including scalar and 3033 :ref:`aggregate <t_aggregate>` types. This is often used to avoid 3034 having to print large zero initializers (e.g. for large arrays) and 3035 is always exactly equivalent to using explicit zero initializers. 3036**Metadata node** 3037 A metadata node is a constant tuple without types. For example: 3038 "``!{!0, !{!2, !0}, !"test"}``". Metadata can reference constant values, 3039 for example: "``!{!0, i32 0, i8* @global, i64 (i64)* @function, !"str"}``". 3040 Unlike other typed constants that are meant to be interpreted as part of 3041 the instruction stream, metadata is a place to attach additional 3042 information such as debug info. 3043 3044Global Variable and Function Addresses 3045-------------------------------------- 3046 3047The addresses of :ref:`global variables <globalvars>` and 3048:ref:`functions <functionstructure>` are always implicitly valid 3049(link-time) constants. These constants are explicitly referenced when 3050the :ref:`identifier for the global <identifiers>` is used and always have 3051:ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM 3052file: 3053 3054.. code-block:: llvm 3055 3056 @X = global i32 17 3057 @Y = global i32 42 3058 @Z = global [2 x i32*] [ i32* @X, i32* @Y ] 3059 3060.. _undefvalues: 3061 3062Undefined Values 3063---------------- 3064 3065The string '``undef``' can be used anywhere a constant is expected, and 3066indicates that the user of the value may receive an unspecified 3067bit-pattern. Undefined values may be of any type (other than '``label``' 3068or '``void``') and be used anywhere a constant is permitted. 3069 3070Undefined values are useful because they indicate to the compiler that 3071the program is well defined no matter what value is used. This gives the 3072compiler more freedom to optimize. Here are some examples of 3073(potentially surprising) transformations that are valid (in pseudo IR): 3074 3075.. code-block:: llvm 3076 3077 %A = add %X, undef 3078 %B = sub %X, undef 3079 %C = xor %X, undef 3080 Safe: 3081 %A = undef 3082 %B = undef 3083 %C = undef 3084 3085This is safe because all of the output bits are affected by the undef 3086bits. Any output bit can have a zero or one depending on the input bits. 3087 3088.. code-block:: llvm 3089 3090 %A = or %X, undef 3091 %B = and %X, undef 3092 Safe: 3093 %A = -1 3094 %B = 0 3095 Safe: 3096 %A = %X ;; By choosing undef as 0 3097 %B = %X ;; By choosing undef as -1 3098 Unsafe: 3099 %A = undef 3100 %B = undef 3101 3102These logical operations have bits that are not always affected by the 3103input. For example, if ``%X`` has a zero bit, then the output of the 3104'``and``' operation will always be a zero for that bit, no matter what 3105the corresponding bit from the '``undef``' is. As such, it is unsafe to 3106optimize or assume that the result of the '``and``' is '``undef``'. 3107However, it is safe to assume that all bits of the '``undef``' could be 31080, and optimize the '``and``' to 0. Likewise, it is safe to assume that 3109all the bits of the '``undef``' operand to the '``or``' could be set, 3110allowing the '``or``' to be folded to -1. 3111 3112.. code-block:: llvm 3113 3114 %A = select undef, %X, %Y 3115 %B = select undef, 42, %Y 3116 %C = select %X, %Y, undef 3117 Safe: 3118 %A = %X (or %Y) 3119 %B = 42 (or %Y) 3120 %C = %Y 3121 Unsafe: 3122 %A = undef 3123 %B = undef 3124 %C = undef 3125 3126This set of examples shows that undefined '``select``' (and conditional 3127branch) conditions can go *either way*, but they have to come from one 3128of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were 3129both known to have a clear low bit, then ``%A`` would have to have a 3130cleared low bit. However, in the ``%C`` example, the optimizer is 3131allowed to assume that the '``undef``' operand could be the same as 3132``%Y``, allowing the whole '``select``' to be eliminated. 3133 3134.. code-block:: text 3135 3136 %A = xor undef, undef 3137 3138 %B = undef 3139 %C = xor %B, %B 3140 3141 %D = undef 3142 %E = icmp slt %D, 4 3143 %F = icmp gte %D, 4 3144 3145 Safe: 3146 %A = undef 3147 %B = undef 3148 %C = undef 3149 %D = undef 3150 %E = undef 3151 %F = undef 3152 3153This example points out that two '``undef``' operands are not 3154necessarily the same. This can be surprising to people (and also matches 3155C semantics) where they assume that "``X^X``" is always zero, even if 3156``X`` is undefined. This isn't true for a number of reasons, but the 3157short answer is that an '``undef``' "variable" can arbitrarily change 3158its value over its "live range". This is true because the variable 3159doesn't actually *have a live range*. Instead, the value is logically 3160read from arbitrary registers that happen to be around when needed, so 3161the value is not necessarily consistent over time. In fact, ``%A`` and 3162``%C`` need to have the same semantics or the core LLVM "replace all 3163uses with" concept would not hold. 3164 3165.. code-block:: llvm 3166 3167 %A = sdiv undef, %X 3168 %B = sdiv %X, undef 3169 Safe: 3170 %A = 0 3171 b: unreachable 3172 3173These examples show the crucial difference between an *undefined value* 3174and *undefined behavior*. An undefined value (like '``undef``') is 3175allowed to have an arbitrary bit-pattern. This means that the ``%A`` 3176operation can be constant folded to '``0``', because the '``undef``' 3177could be zero, and zero divided by any value is zero. 3178However, in the second example, we can make a more aggressive 3179assumption: because the ``undef`` is allowed to be an arbitrary value, 3180we are allowed to assume that it could be zero. Since a divide by zero 3181has *undefined behavior*, we are allowed to assume that the operation 3182does not execute at all. This allows us to delete the divide and all 3183code after it. Because the undefined operation "can't happen", the 3184optimizer can assume that it occurs in dead code. 3185 3186.. code-block:: text 3187 3188 a: store undef -> %X 3189 b: store %X -> undef 3190 Safe: 3191 a: <deleted> 3192 b: unreachable 3193 3194A store *of* an undefined value can be assumed to not have any effect; 3195we can assume that the value is overwritten with bits that happen to 3196match what was already there. However, a store *to* an undefined 3197location could clobber arbitrary memory, therefore, it has undefined 3198behavior. 3199 3200.. _poisonvalues: 3201 3202Poison Values 3203------------- 3204 3205Poison values are similar to :ref:`undef values <undefvalues>`, however 3206they also represent the fact that an instruction or constant expression 3207that cannot evoke side effects has nevertheless detected a condition 3208that results in undefined behavior. 3209 3210There is currently no way of representing a poison value in the IR; they 3211only exist when produced by operations such as :ref:`add <i_add>` with 3212the ``nsw`` flag. 3213 3214Poison value behavior is defined in terms of value *dependence*: 3215 3216- Values other than :ref:`phi <i_phi>` nodes depend on their operands. 3217- :ref:`Phi <i_phi>` nodes depend on the operand corresponding to 3218 their dynamic predecessor basic block. 3219- Function arguments depend on the corresponding actual argument values 3220 in the dynamic callers of their functions. 3221- :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>` 3222 instructions that dynamically transfer control back to them. 3223- :ref:`Invoke <i_invoke>` instructions depend on the 3224 :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing 3225 call instructions that dynamically transfer control back to them. 3226- Non-volatile loads and stores depend on the most recent stores to all 3227 of the referenced memory addresses, following the order in the IR 3228 (including loads and stores implied by intrinsics such as 3229 :ref:`@llvm.memcpy <int_memcpy>`.) 3230- An instruction with externally visible side effects depends on the 3231 most recent preceding instruction with externally visible side 3232 effects, following the order in the IR. (This includes :ref:`volatile 3233 operations <volatile>`.) 3234- An instruction *control-depends* on a :ref:`terminator 3235 instruction <terminators>` if the terminator instruction has 3236 multiple successors and the instruction is always executed when 3237 control transfers to one of the successors, and may not be executed 3238 when control is transferred to another. 3239- Additionally, an instruction also *control-depends* on a terminator 3240 instruction if the set of instructions it otherwise depends on would 3241 be different if the terminator had transferred control to a different 3242 successor. 3243- Dependence is transitive. 3244 3245Poison values have the same behavior as :ref:`undef values <undefvalues>`, 3246with the additional effect that any instruction that has a *dependence* 3247on a poison value has undefined behavior. 3248 3249Here are some examples: 3250 3251.. code-block:: llvm 3252 3253 entry: 3254 %poison = sub nuw i32 0, 1 ; Results in a poison value. 3255 %still_poison = and i32 %poison, 0 ; 0, but also poison. 3256 %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison 3257 store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned 3258 3259 store i32 %poison, i32* @g ; Poison value stored to memory. 3260 %poison2 = load i32, i32* @g ; Poison value loaded back from memory. 3261 3262 store volatile i32 %poison, i32* @g ; External observation; undefined behavior. 3263 3264 %narrowaddr = bitcast i32* @g to i16* 3265 %wideaddr = bitcast i32* @g to i64* 3266 %poison3 = load i16, i16* %narrowaddr ; Returns a poison value. 3267 %poison4 = load i64, i64* %wideaddr ; Returns a poison value. 3268 3269 %cmp = icmp slt i32 %poison, 0 ; Returns a poison value. 3270 br i1 %cmp, label %true, label %end ; Branch to either destination. 3271 3272 true: 3273 store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so 3274 ; it has undefined behavior. 3275 br label %end 3276 3277 end: 3278 %p = phi i32 [ 0, %entry ], [ 1, %true ] 3279 ; Both edges into this PHI are 3280 ; control-dependent on %cmp, so this 3281 ; always results in a poison value. 3282 3283 store volatile i32 0, i32* @g ; This would depend on the store in %true 3284 ; if %cmp is true, or the store in %entry 3285 ; otherwise, so this is undefined behavior. 3286 3287 br i1 %cmp, label %second_true, label %second_end 3288 ; The same branch again, but this time the 3289 ; true block doesn't have side effects. 3290 3291 second_true: 3292 ; No side effects! 3293 ret void 3294 3295 second_end: 3296 store volatile i32 0, i32* @g ; This time, the instruction always depends 3297 ; on the store in %end. Also, it is 3298 ; control-equivalent to %end, so this is 3299 ; well-defined (ignoring earlier undefined 3300 ; behavior in this example). 3301 3302.. _blockaddress: 3303 3304Addresses of Basic Blocks 3305------------------------- 3306 3307``blockaddress(@function, %block)`` 3308 3309The '``blockaddress``' constant computes the address of the specified 3310basic block in the specified function, and always has an ``i8*`` type. 3311Taking the address of the entry block is illegal. 3312 3313This value only has defined behavior when used as an operand to the 3314':ref:`indirectbr <i_indirectbr>`' or ':ref:`callbr <i_callbr>`'instruction, or 3315for comparisons against null. Pointer equality tests between labels addresses 3316results in undefined behavior --- though, again, comparison against null is ok, 3317and no label is equal to the null pointer. This may be passed around as an 3318opaque pointer sized value as long as the bits are not inspected. This 3319allows ``ptrtoint`` and arithmetic to be performed on these values so 3320long as the original value is reconstituted before the ``indirectbr`` or 3321``callbr`` instruction. 3322 3323Finally, some targets may provide defined semantics when using the value 3324as the operand to an inline assembly, but that is target specific. 3325 3326.. _constantexprs: 3327 3328Constant Expressions 3329-------------------- 3330 3331Constant expressions are used to allow expressions involving other 3332constants to be used as constants. Constant expressions may be of any 3333:ref:`first class <t_firstclass>` type and may involve any LLVM operation 3334that does not have side effects (e.g. load and call are not supported). 3335The following is the syntax for constant expressions: 3336 3337``trunc (CST to TYPE)`` 3338 Perform the :ref:`trunc operation <i_trunc>` on constants. 3339``zext (CST to TYPE)`` 3340 Perform the :ref:`zext operation <i_zext>` on constants. 3341``sext (CST to TYPE)`` 3342 Perform the :ref:`sext operation <i_sext>` on constants. 3343``fptrunc (CST to TYPE)`` 3344 Truncate a floating-point constant to another floating-point type. 3345 The size of CST must be larger than the size of TYPE. Both types 3346 must be floating-point. 3347``fpext (CST to TYPE)`` 3348 Floating-point extend a constant to another type. The size of CST 3349 must be smaller or equal to the size of TYPE. Both types must be 3350 floating-point. 3351``fptoui (CST to TYPE)`` 3352 Convert a floating-point constant to the corresponding unsigned 3353 integer constant. TYPE must be a scalar or vector integer type. CST 3354 must be of scalar or vector floating-point type. Both CST and TYPE 3355 must be scalars, or vectors of the same number of elements. If the 3356 value won't fit in the integer type, the result is a 3357 :ref:`poison value <poisonvalues>`. 3358``fptosi (CST to TYPE)`` 3359 Convert a floating-point constant to the corresponding signed 3360 integer constant. TYPE must be a scalar or vector integer type. CST 3361 must be of scalar or vector floating-point type. Both CST and TYPE 3362 must be scalars, or vectors of the same number of elements. If the 3363 value won't fit in the integer type, the result is a 3364 :ref:`poison value <poisonvalues>`. 3365``uitofp (CST to TYPE)`` 3366 Convert an unsigned integer constant to the corresponding 3367 floating-point constant. TYPE must be a scalar or vector floating-point 3368 type. CST must be of scalar or vector integer type. Both CST and TYPE must 3369 be scalars, or vectors of the same number of elements. 3370``sitofp (CST to TYPE)`` 3371 Convert a signed integer constant to the corresponding floating-point 3372 constant. TYPE must be a scalar or vector floating-point type. 3373 CST must be of scalar or vector integer type. Both CST and TYPE must 3374 be scalars, or vectors of the same number of elements. 3375``ptrtoint (CST to TYPE)`` 3376 Perform the :ref:`ptrtoint operation <i_ptrtoint>` on constants. 3377``inttoptr (CST to TYPE)`` 3378 Perform the :ref:`inttoptr operation <i_inttoptr>` on constants. 3379 This one is *really* dangerous! 3380``bitcast (CST to TYPE)`` 3381 Convert a constant, CST, to another TYPE. 3382 The constraints of the operands are the same as those for the 3383 :ref:`bitcast instruction <i_bitcast>`. 3384``addrspacecast (CST to TYPE)`` 3385 Convert a constant pointer or constant vector of pointer, CST, to another 3386 TYPE in a different address space. The constraints of the operands are the 3387 same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`. 3388``getelementptr (TY, CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (TY, CSTPTR, IDX0, IDX1, ...)`` 3389 Perform the :ref:`getelementptr operation <i_getelementptr>` on 3390 constants. As with the :ref:`getelementptr <i_getelementptr>` 3391 instruction, the index list may have one or more indexes, which are 3392 required to make sense for the type of "pointer to TY". 3393``select (COND, VAL1, VAL2)`` 3394 Perform the :ref:`select operation <i_select>` on constants. 3395``icmp COND (VAL1, VAL2)`` 3396 Perform the :ref:`icmp operation <i_icmp>` on constants. 3397``fcmp COND (VAL1, VAL2)`` 3398 Perform the :ref:`fcmp operation <i_fcmp>` on constants. 3399``extractelement (VAL, IDX)`` 3400 Perform the :ref:`extractelement operation <i_extractelement>` on 3401 constants. 3402``insertelement (VAL, ELT, IDX)`` 3403 Perform the :ref:`insertelement operation <i_insertelement>` on 3404 constants. 3405``shufflevector (VEC1, VEC2, IDXMASK)`` 3406 Perform the :ref:`shufflevector operation <i_shufflevector>` on 3407 constants. 3408``extractvalue (VAL, IDX0, IDX1, ...)`` 3409 Perform the :ref:`extractvalue operation <i_extractvalue>` on 3410 constants. The index list is interpreted in a similar manner as 3411 indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At 3412 least one index value must be specified. 3413``insertvalue (VAL, ELT, IDX0, IDX1, ...)`` 3414 Perform the :ref:`insertvalue operation <i_insertvalue>` on constants. 3415 The index list is interpreted in a similar manner as indices in a 3416 ':ref:`getelementptr <i_getelementptr>`' operation. At least one index 3417 value must be specified. 3418``OPCODE (LHS, RHS)`` 3419 Perform the specified operation of the LHS and RHS constants. OPCODE 3420 may be any of the :ref:`binary <binaryops>` or :ref:`bitwise 3421 binary <bitwiseops>` operations. The constraints on operands are 3422 the same as those for the corresponding instruction (e.g. no bitwise 3423 operations on floating-point values are allowed). 3424 3425Other Values 3426============ 3427 3428.. _inlineasmexprs: 3429 3430Inline Assembler Expressions 3431---------------------------- 3432 3433LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level 3434Inline Assembly <moduleasm>`) through the use of a special value. This value 3435represents the inline assembler as a template string (containing the 3436instructions to emit), a list of operand constraints (stored as a string), a 3437flag that indicates whether or not the inline asm expression has side effects, 3438and a flag indicating whether the function containing the asm needs to align its 3439stack conservatively. 3440 3441The template string supports argument substitution of the operands using "``$``" 3442followed by a number, to indicate substitution of the given register/memory 3443location, as specified by the constraint string. "``${NUM:MODIFIER}``" may also 3444be used, where ``MODIFIER`` is a target-specific annotation for how to print the 3445operand (See :ref:`inline-asm-modifiers`). 3446 3447A literal "``$``" may be included by using "``$$``" in the template. To include 3448other special characters into the output, the usual "``\XX``" escapes may be 3449used, just as in other strings. Note that after template substitution, the 3450resulting assembly string is parsed by LLVM's integrated assembler unless it is 3451disabled -- even when emitting a ``.s`` file -- and thus must contain assembly 3452syntax known to LLVM. 3453 3454LLVM also supports a few more substitions useful for writing inline assembly: 3455 3456- ``${:uid}``: Expands to a decimal integer unique to this inline assembly blob. 3457 This substitution is useful when declaring a local label. Many standard 3458 compiler optimizations, such as inlining, may duplicate an inline asm blob. 3459 Adding a blob-unique identifier ensures that the two labels will not conflict 3460 during assembly. This is used to implement `GCC's %= special format 3461 string <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_. 3462- ``${:comment}``: Expands to the comment character of the current target's 3463 assembly dialect. This is usually ``#``, but many targets use other strings, 3464 such as ``;``, ``//``, or ``!``. 3465- ``${:private}``: Expands to the assembler private label prefix. Labels with 3466 this prefix will not appear in the symbol table of the assembled object. 3467 Typically the prefix is ``L``, but targets may use other strings. ``.L`` is 3468 relatively popular. 3469 3470LLVM's support for inline asm is modeled closely on the requirements of Clang's 3471GCC-compatible inline-asm support. Thus, the feature-set and the constraint and 3472modifier codes listed here are similar or identical to those in GCC's inline asm 3473support. However, to be clear, the syntax of the template and constraint strings 3474described here is *not* the same as the syntax accepted by GCC and Clang, and, 3475while most constraint letters are passed through as-is by Clang, some get 3476translated to other codes when converting from the C source to the LLVM 3477assembly. 3478 3479An example inline assembler expression is: 3480 3481.. code-block:: llvm 3482 3483 i32 (i32) asm "bswap $0", "=r,r" 3484 3485Inline assembler expressions may **only** be used as the callee operand 3486of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction. 3487Thus, typically we have: 3488 3489.. code-block:: llvm 3490 3491 %X = call i32 asm "bswap $0", "=r,r"(i32 %Y) 3492 3493Inline asms with side effects not visible in the constraint list must be 3494marked as having side effects. This is done through the use of the 3495'``sideeffect``' keyword, like so: 3496 3497.. code-block:: llvm 3498 3499 call void asm sideeffect "eieio", ""() 3500 3501In some cases inline asms will contain code that will not work unless 3502the stack is aligned in some way, such as calls or SSE instructions on 3503x86, yet will not contain code that does that alignment within the asm. 3504The compiler should make conservative assumptions about what the asm 3505might contain and should generate its usual stack alignment code in the 3506prologue if the '``alignstack``' keyword is present: 3507 3508.. code-block:: llvm 3509 3510 call void asm alignstack "eieio", ""() 3511 3512Inline asms also support using non-standard assembly dialects. The 3513assumed dialect is ATT. When the '``inteldialect``' keyword is present, 3514the inline asm is using the Intel dialect. Currently, ATT and Intel are 3515the only supported dialects. An example is: 3516 3517.. code-block:: llvm 3518 3519 call void asm inteldialect "eieio", ""() 3520 3521If multiple keywords appear the '``sideeffect``' keyword must come 3522first, the '``alignstack``' keyword second and the '``inteldialect``' 3523keyword last. 3524 3525Inline Asm Constraint String 3526^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3527 3528The constraint list is a comma-separated string, each element containing one or 3529more constraint codes. 3530 3531For each element in the constraint list an appropriate register or memory 3532operand will be chosen, and it will be made available to assembly template 3533string expansion as ``$0`` for the first constraint in the list, ``$1`` for the 3534second, etc. 3535 3536There are three different types of constraints, which are distinguished by a 3537prefix symbol in front of the constraint code: Output, Input, and Clobber. The 3538constraints must always be given in that order: outputs first, then inputs, then 3539clobbers. They cannot be intermingled. 3540 3541There are also three different categories of constraint codes: 3542 3543- Register constraint. This is either a register class, or a fixed physical 3544 register. This kind of constraint will allocate a register, and if necessary, 3545 bitcast the argument or result to the appropriate type. 3546- Memory constraint. This kind of constraint is for use with an instruction 3547 taking a memory operand. Different constraints allow for different addressing 3548 modes used by the target. 3549- Immediate value constraint. This kind of constraint is for an integer or other 3550 immediate value which can be rendered directly into an instruction. The 3551 various target-specific constraints allow the selection of a value in the 3552 proper range for the instruction you wish to use it with. 3553 3554Output constraints 3555"""""""""""""""""" 3556 3557Output constraints are specified by an "``=``" prefix (e.g. "``=r``"). This 3558indicates that the assembly will write to this operand, and the operand will 3559then be made available as a return value of the ``asm`` expression. Output 3560constraints do not consume an argument from the call instruction. (Except, see 3561below about indirect outputs). 3562 3563Normally, it is expected that no output locations are written to by the assembly 3564expression until *all* of the inputs have been read. As such, LLVM may assign 3565the same register to an output and an input. If this is not safe (e.g. if the 3566assembly contains two instructions, where the first writes to one output, and 3567the second reads an input and writes to a second output), then the "``&``" 3568modifier must be used (e.g. "``=&r``") to specify that the output is an 3569"early-clobber" output. Marking an output as "early-clobber" ensures that LLVM 3570will not use the same register for any inputs (other than an input tied to this 3571output). 3572 3573Input constraints 3574""""""""""""""""" 3575 3576Input constraints do not have a prefix -- just the constraint codes. Each input 3577constraint will consume one argument from the call instruction. It is not 3578permitted for the asm to write to any input register or memory location (unless 3579that input is tied to an output). Note also that multiple inputs may all be 3580assigned to the same register, if LLVM can determine that they necessarily all 3581contain the same value. 3582 3583Instead of providing a Constraint Code, input constraints may also "tie" 3584themselves to an output constraint, by providing an integer as the constraint 3585string. Tied inputs still consume an argument from the call instruction, and 3586take up a position in the asm template numbering as is usual -- they will simply 3587be constrained to always use the same register as the output they've been tied 3588to. For example, a constraint string of "``=r,0``" says to assign a register for 3589output, and use that register as an input as well (it being the 0'th 3590constraint). 3591 3592It is permitted to tie an input to an "early-clobber" output. In that case, no 3593*other* input may share the same register as the input tied to the early-clobber 3594(even when the other input has the same value). 3595 3596You may only tie an input to an output which has a register constraint, not a 3597memory constraint. Only a single input may be tied to an output. 3598 3599There is also an "interesting" feature which deserves a bit of explanation: if a 3600register class constraint allocates a register which is too small for the value 3601type operand provided as input, the input value will be split into multiple 3602registers, and all of them passed to the inline asm. 3603 3604However, this feature is often not as useful as you might think. 3605 3606Firstly, the registers are *not* guaranteed to be consecutive. So, on those 3607architectures that have instructions which operate on multiple consecutive 3608instructions, this is not an appropriate way to support them. (e.g. the 32-bit 3609SparcV8 has a 64-bit load, which instruction takes a single 32-bit register. The 3610hardware then loads into both the named register, and the next register. This 3611feature of inline asm would not be useful to support that.) 3612 3613A few of the targets provide a template string modifier allowing explicit access 3614to the second register of a two-register operand (e.g. MIPS ``L``, ``M``, and 3615``D``). On such an architecture, you can actually access the second allocated 3616register (yet, still, not any subsequent ones). But, in that case, you're still 3617probably better off simply splitting the value into two separate operands, for 3618clarity. (e.g. see the description of the ``A`` constraint on X86, which, 3619despite existing only for use with this feature, is not really a good idea to 3620use) 3621 3622Indirect inputs and outputs 3623""""""""""""""""""""""""""" 3624 3625Indirect output or input constraints can be specified by the "``*``" modifier 3626(which goes after the "``=``" in case of an output). This indicates that the asm 3627will write to or read from the contents of an *address* provided as an input 3628argument. (Note that in this way, indirect outputs act more like an *input* than 3629an output: just like an input, they consume an argument of the call expression, 3630rather than producing a return value. An indirect output constraint is an 3631"output" only in that the asm is expected to write to the contents of the input 3632memory location, instead of just read from it). 3633 3634This is most typically used for memory constraint, e.g. "``=*m``", to pass the 3635address of a variable as a value. 3636 3637It is also possible to use an indirect *register* constraint, but only on output 3638(e.g. "``=*r``"). This will cause LLVM to allocate a register for an output 3639value normally, and then, separately emit a store to the address provided as 3640input, after the provided inline asm. (It's not clear what value this 3641functionality provides, compared to writing the store explicitly after the asm 3642statement, and it can only produce worse code, since it bypasses many 3643optimization passes. I would recommend not using it.) 3644 3645 3646Clobber constraints 3647""""""""""""""""""" 3648 3649A clobber constraint is indicated by a "``~``" prefix. A clobber does not 3650consume an input operand, nor generate an output. Clobbers cannot use any of the 3651general constraint code letters -- they may use only explicit register 3652constraints, e.g. "``~{eax}``". The one exception is that a clobber string of 3653"``~{memory}``" indicates that the assembly writes to arbitrary undeclared 3654memory locations -- not only the memory pointed to by a declared indirect 3655output. 3656 3657Note that clobbering named registers that are also present in output 3658constraints is not legal. 3659 3660 3661Constraint Codes 3662"""""""""""""""" 3663After a potential prefix comes constraint code, or codes. 3664 3665A Constraint Code is either a single letter (e.g. "``r``"), a "``^``" character 3666followed by two letters (e.g. "``^wc``"), or "``{``" register-name "``}``" 3667(e.g. "``{eax}``"). 3668 3669The one and two letter constraint codes are typically chosen to be the same as 3670GCC's constraint codes. 3671 3672A single constraint may include one or more than constraint code in it, leaving 3673it up to LLVM to choose which one to use. This is included mainly for 3674compatibility with the translation of GCC inline asm coming from clang. 3675 3676There are two ways to specify alternatives, and either or both may be used in an 3677inline asm constraint list: 3678 36791) Append the codes to each other, making a constraint code set. E.g. "``im``" 3680 or "``{eax}m``". This means "choose any of the options in the set". The 3681 choice of constraint is made independently for each constraint in the 3682 constraint list. 3683 36842) Use "``|``" between constraint code sets, creating alternatives. Every 3685 constraint in the constraint list must have the same number of alternative 3686 sets. With this syntax, the same alternative in *all* of the items in the 3687 constraint list will be chosen together. 3688 3689Putting those together, you might have a two operand constraint string like 3690``"rm|r,ri|rm"``. This indicates that if operand 0 is ``r`` or ``m``, then 3691operand 1 may be one of ``r`` or ``i``. If operand 0 is ``r``, then operand 1 3692may be one of ``r`` or ``m``. But, operand 0 and 1 cannot both be of type m. 3693 3694However, the use of either of the alternatives features is *NOT* recommended, as 3695LLVM is not able to make an intelligent choice about which one to use. (At the 3696point it currently needs to choose, not enough information is available to do so 3697in a smart way.) Thus, it simply tries to make a choice that's most likely to 3698compile, not one that will be optimal performance. (e.g., given "``rm``", it'll 3699always choose to use memory, not registers). And, if given multiple registers, 3700or multiple register classes, it will simply choose the first one. (In fact, it 3701doesn't currently even ensure explicitly specified physical registers are 3702unique, so specifying multiple physical registers as alternatives, like 3703``{r11}{r12},{r11}{r12}``, will assign r11 to both operands, not at all what was 3704intended.) 3705 3706Supported Constraint Code List 3707"""""""""""""""""""""""""""""" 3708 3709The constraint codes are, in general, expected to behave the same way they do in 3710GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C 3711inline asm code which was supported by GCC. A mismatch in behavior between LLVM 3712and GCC likely indicates a bug in LLVM. 3713 3714Some constraint codes are typically supported by all targets: 3715 3716- ``r``: A register in the target's general purpose register class. 3717- ``m``: A memory address operand. It is target-specific what addressing modes 3718 are supported, typical examples are register, or register + register offset, 3719 or register + immediate offset (of some target-specific size). 3720- ``i``: An integer constant (of target-specific width). Allows either a simple 3721 immediate, or a relocatable value. 3722- ``n``: An integer constant -- *not* including relocatable values. 3723- ``s``: An integer constant, but allowing *only* relocatable values. 3724- ``X``: Allows an operand of any kind, no constraint whatsoever. Typically 3725 useful to pass a label for an asm branch or call. 3726 3727 .. FIXME: but that surely isn't actually okay to jump out of an asm 3728 block without telling llvm about the control transfer???) 3729 3730- ``{register-name}``: Requires exactly the named physical register. 3731 3732Other constraints are target-specific: 3733 3734AArch64: 3735 3736- ``z``: An immediate integer 0. Outputs ``WZR`` or ``XZR``, as appropriate. 3737- ``I``: An immediate integer valid for an ``ADD`` or ``SUB`` instruction, 3738 i.e. 0 to 4095 with optional shift by 12. 3739- ``J``: An immediate integer that, when negated, is valid for an ``ADD`` or 3740 ``SUB`` instruction, i.e. -1 to -4095 with optional left shift by 12. 3741- ``K``: An immediate integer that is valid for the 'bitmask immediate 32' of a 3742 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 32-bit register. 3743- ``L``: An immediate integer that is valid for the 'bitmask immediate 64' of a 3744 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 64-bit register. 3745- ``M``: An immediate integer for use with the ``MOV`` assembly alias on a 3746 32-bit register. This is a superset of ``K``: in addition to the bitmask 3747 immediate, also allows immediate integers which can be loaded with a single 3748 ``MOVZ`` or ``MOVL`` instruction. 3749- ``N``: An immediate integer for use with the ``MOV`` assembly alias on a 3750 64-bit register. This is a superset of ``L``. 3751- ``Q``: Memory address operand must be in a single register (no 3752 offsets). (However, LLVM currently does this for the ``m`` constraint as 3753 well.) 3754- ``r``: A 32 or 64-bit integer register (W* or X*). 3755- ``w``: A 32, 64, or 128-bit floating-point/SIMD register. 3756- ``x``: A lower 128-bit floating-point/SIMD register (``V0`` to ``V15``). 3757 3758AMDGPU: 3759 3760- ``r``: A 32 or 64-bit integer register. 3761- ``[0-9]v``: The 32-bit VGPR register, number 0-9. 3762- ``[0-9]s``: The 32-bit SGPR register, number 0-9. 3763 3764 3765All ARM modes: 3766 3767- ``Q``, ``Um``, ``Un``, ``Uq``, ``Us``, ``Ut``, ``Uv``, ``Uy``: Memory address 3768 operand. Treated the same as operand ``m``, at the moment. 3769 3770ARM and ARM's Thumb2 mode: 3771 3772- ``j``: An immediate integer between 0 and 65535 (valid for ``MOVW``) 3773- ``I``: An immediate integer valid for a data-processing instruction. 3774- ``J``: An immediate integer between -4095 and 4095. 3775- ``K``: An immediate integer whose bitwise inverse is valid for a 3776 data-processing instruction. (Can be used with template modifier "``B``" to 3777 print the inverted value). 3778- ``L``: An immediate integer whose negation is valid for a data-processing 3779 instruction. (Can be used with template modifier "``n``" to print the negated 3780 value). 3781- ``M``: A power of two or a integer between 0 and 32. 3782- ``N``: Invalid immediate constraint. 3783- ``O``: Invalid immediate constraint. 3784- ``r``: A general-purpose 32-bit integer register (``r0-r15``). 3785- ``l``: In Thumb2 mode, low 32-bit GPR registers (``r0-r7``). In ARM mode, same 3786 as ``r``. 3787- ``h``: In Thumb2 mode, a high 32-bit GPR register (``r8-r15``). In ARM mode, 3788 invalid. 3789- ``w``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s31``, 3790 ``d0-d31``, or ``q0-q15``. 3791- ``x``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s15``, 3792 ``d0-d7``, or ``q0-q3``. 3793- ``t``: A low floating-point/SIMD register: ``s0-s31``, ``d0-d16``, or 3794 ``q0-q8``. 3795 3796ARM's Thumb1 mode: 3797 3798- ``I``: An immediate integer between 0 and 255. 3799- ``J``: An immediate integer between -255 and -1. 3800- ``K``: An immediate integer between 0 and 255, with optional left-shift by 3801 some amount. 3802- ``L``: An immediate integer between -7 and 7. 3803- ``M``: An immediate integer which is a multiple of 4 between 0 and 1020. 3804- ``N``: An immediate integer between 0 and 31. 3805- ``O``: An immediate integer which is a multiple of 4 between -508 and 508. 3806- ``r``: A low 32-bit GPR register (``r0-r7``). 3807- ``l``: A low 32-bit GPR register (``r0-r7``). 3808- ``h``: A high GPR register (``r0-r7``). 3809- ``w``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s31``, 3810 ``d0-d31``, or ``q0-q15``. 3811- ``x``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s15``, 3812 ``d0-d7``, or ``q0-q3``. 3813- ``t``: A low floating-point/SIMD register: ``s0-s31``, ``d0-d16``, or 3814 ``q0-q8``. 3815 3816 3817Hexagon: 3818 3819- ``o``, ``v``: A memory address operand, treated the same as constraint ``m``, 3820 at the moment. 3821- ``r``: A 32 or 64-bit register. 3822 3823MSP430: 3824 3825- ``r``: An 8 or 16-bit register. 3826 3827MIPS: 3828 3829- ``I``: An immediate signed 16-bit integer. 3830- ``J``: An immediate integer zero. 3831- ``K``: An immediate unsigned 16-bit integer. 3832- ``L``: An immediate 32-bit integer, where the lower 16 bits are 0. 3833- ``N``: An immediate integer between -65535 and -1. 3834- ``O``: An immediate signed 15-bit integer. 3835- ``P``: An immediate integer between 1 and 65535. 3836- ``m``: A memory address operand. In MIPS-SE mode, allows a base address 3837 register plus 16-bit immediate offset. In MIPS mode, just a base register. 3838- ``R``: A memory address operand. In MIPS-SE mode, allows a base address 3839 register plus a 9-bit signed offset. In MIPS mode, the same as constraint 3840 ``m``. 3841- ``ZC``: A memory address operand, suitable for use in a ``pref``, ``ll``, or 3842 ``sc`` instruction on the given subtarget (details vary). 3843- ``r``, ``d``, ``y``: A 32 or 64-bit GPR register. 3844- ``f``: A 32 or 64-bit FPU register (``F0-F31``), or a 128-bit MSA register 3845 (``W0-W31``). In the case of MSA registers, it is recommended to use the ``w`` 3846 argument modifier for compatibility with GCC. 3847- ``c``: A 32-bit or 64-bit GPR register suitable for indirect jump (always 3848 ``25``). 3849- ``l``: The ``lo`` register, 32 or 64-bit. 3850- ``x``: Invalid. 3851 3852NVPTX: 3853 3854- ``b``: A 1-bit integer register. 3855- ``c`` or ``h``: A 16-bit integer register. 3856- ``r``: A 32-bit integer register. 3857- ``l`` or ``N``: A 64-bit integer register. 3858- ``f``: A 32-bit float register. 3859- ``d``: A 64-bit float register. 3860 3861 3862PowerPC: 3863 3864- ``I``: An immediate signed 16-bit integer. 3865- ``J``: An immediate unsigned 16-bit integer, shifted left 16 bits. 3866- ``K``: An immediate unsigned 16-bit integer. 3867- ``L``: An immediate signed 16-bit integer, shifted left 16 bits. 3868- ``M``: An immediate integer greater than 31. 3869- ``N``: An immediate integer that is an exact power of 2. 3870- ``O``: The immediate integer constant 0. 3871- ``P``: An immediate integer constant whose negation is a signed 16-bit 3872 constant. 3873- ``es``, ``o``, ``Q``, ``Z``, ``Zy``: A memory address operand, currently 3874 treated the same as ``m``. 3875- ``r``: A 32 or 64-bit integer register. 3876- ``b``: A 32 or 64-bit integer register, excluding ``R0`` (that is: 3877 ``R1-R31``). 3878- ``f``: A 32 or 64-bit float register (``F0-F31``), or when QPX is enabled, a 3879 128 or 256-bit QPX register (``Q0-Q31``; aliases the ``F`` registers). 3880- ``v``: For ``4 x f32`` or ``4 x f64`` types, when QPX is enabled, a 3881 128 or 256-bit QPX register (``Q0-Q31``), otherwise a 128-bit 3882 altivec vector register (``V0-V31``). 3883 3884 .. FIXME: is this a bug that v accepts QPX registers? I think this 3885 is supposed to only use the altivec vector registers? 3886 3887- ``y``: Condition register (``CR0-CR7``). 3888- ``wc``: An individual CR bit in a CR register. 3889- ``wa``, ``wd``, ``wf``: Any 128-bit VSX vector register, from the full VSX 3890 register set (overlapping both the floating-point and vector register files). 3891- ``ws``: A 32 or 64-bit floating-point register, from the full VSX register 3892 set. 3893 3894Sparc: 3895 3896- ``I``: An immediate 13-bit signed integer. 3897- ``r``: A 32-bit integer register. 3898- ``f``: Any floating-point register on SparcV8, or a floating-point 3899 register in the "low" half of the registers on SparcV9. 3900- ``e``: Any floating-point register. (Same as ``f`` on SparcV8.) 3901 3902SystemZ: 3903 3904- ``I``: An immediate unsigned 8-bit integer. 3905- ``J``: An immediate unsigned 12-bit integer. 3906- ``K``: An immediate signed 16-bit integer. 3907- ``L``: An immediate signed 20-bit integer. 3908- ``M``: An immediate integer 0x7fffffff. 3909- ``Q``: A memory address operand with a base address and a 12-bit immediate 3910 unsigned displacement. 3911- ``R``: A memory address operand with a base address, a 12-bit immediate 3912 unsigned displacement, and an index register. 3913- ``S``: A memory address operand with a base address and a 20-bit immediate 3914 signed displacement. 3915- ``T``: A memory address operand with a base address, a 20-bit immediate 3916 signed displacement, and an index register. 3917- ``r`` or ``d``: A 32, 64, or 128-bit integer register. 3918- ``a``: A 32, 64, or 128-bit integer address register (excludes R0, which in an 3919 address context evaluates as zero). 3920- ``h``: A 32-bit value in the high part of a 64bit data register 3921 (LLVM-specific) 3922- ``f``: A 32, 64, or 128-bit floating-point register. 3923 3924X86: 3925 3926- ``I``: An immediate integer between 0 and 31. 3927- ``J``: An immediate integer between 0 and 64. 3928- ``K``: An immediate signed 8-bit integer. 3929- ``L``: An immediate integer, 0xff or 0xffff or (in 64-bit mode only) 3930 0xffffffff. 3931- ``M``: An immediate integer between 0 and 3. 3932- ``N``: An immediate unsigned 8-bit integer. 3933- ``O``: An immediate integer between 0 and 127. 3934- ``e``: An immediate 32-bit signed integer. 3935- ``Z``: An immediate 32-bit unsigned integer. 3936- ``o``, ``v``: Treated the same as ``m``, at the moment. 3937- ``q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit 3938 ``l`` integer register. On X86-32, this is the ``a``, ``b``, ``c``, and ``d`` 3939 registers, and on X86-64, it is all of the integer registers. 3940- ``Q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit 3941 ``h`` integer register. This is the ``a``, ``b``, ``c``, and ``d`` registers. 3942- ``r`` or ``l``: An 8, 16, 32, or 64-bit integer register. 3943- ``R``: An 8, 16, 32, or 64-bit "legacy" integer register -- one which has 3944 existed since i386, and can be accessed without the REX prefix. 3945- ``f``: A 32, 64, or 80-bit '387 FPU stack pseudo-register. 3946- ``y``: A 64-bit MMX register, if MMX is enabled. 3947- ``x``: If SSE is enabled: a 32 or 64-bit scalar operand, or 128-bit vector 3948 operand in a SSE register. If AVX is also enabled, can also be a 256-bit 3949 vector operand in an AVX register. If AVX-512 is also enabled, can also be a 3950 512-bit vector operand in an AVX512 register, Otherwise, an error. 3951- ``Y``: The same as ``x``, if *SSE2* is enabled, otherwise an error. 3952- ``A``: Special case: allocates EAX first, then EDX, for a single operand (in 3953 32-bit mode, a 64-bit integer operand will get split into two registers). It 3954 is not recommended to use this constraint, as in 64-bit mode, the 64-bit 3955 operand will get allocated only to RAX -- if two 32-bit operands are needed, 3956 you're better off splitting it yourself, before passing it to the asm 3957 statement. 3958 3959XCore: 3960 3961- ``r``: A 32-bit integer register. 3962 3963 3964.. _inline-asm-modifiers: 3965 3966Asm template argument modifiers 3967^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3968 3969In the asm template string, modifiers can be used on the operand reference, like 3970"``${0:n}``". 3971 3972The modifiers are, in general, expected to behave the same way they do in 3973GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C 3974inline asm code which was supported by GCC. A mismatch in behavior between LLVM 3975and GCC likely indicates a bug in LLVM. 3976 3977Target-independent: 3978 3979- ``c``: Print an immediate integer constant unadorned, without 3980 the target-specific immediate punctuation (e.g. no ``$`` prefix). 3981- ``n``: Negate and print immediate integer constant unadorned, without the 3982 target-specific immediate punctuation (e.g. no ``$`` prefix). 3983- ``l``: Print as an unadorned label, without the target-specific label 3984 punctuation (e.g. no ``$`` prefix). 3985 3986AArch64: 3987 3988- ``w``: Print a GPR register with a ``w*`` name instead of ``x*`` name. E.g., 3989 instead of ``x30``, print ``w30``. 3990- ``x``: Print a GPR register with a ``x*`` name. (this is the default, anyhow). 3991- ``b``, ``h``, ``s``, ``d``, ``q``: Print a floating-point/SIMD register with a 3992 ``b*``, ``h*``, ``s*``, ``d*``, or ``q*`` name, rather than the default of 3993 ``v*``. 3994 3995AMDGPU: 3996 3997- ``r``: No effect. 3998 3999ARM: 4000 4001- ``a``: Print an operand as an address (with ``[`` and ``]`` surrounding a 4002 register). 4003- ``P``: No effect. 4004- ``q``: No effect. 4005- ``y``: Print a VFP single-precision register as an indexed double (e.g. print 4006 as ``d4[1]`` instead of ``s9``) 4007- ``B``: Bitwise invert and print an immediate integer constant without ``#`` 4008 prefix. 4009- ``L``: Print the low 16-bits of an immediate integer constant. 4010- ``M``: Print as a register set suitable for ldm/stm. Also prints *all* 4011 register operands subsequent to the specified one (!), so use carefully. 4012- ``Q``: Print the low-order register of a register-pair, or the low-order 4013 register of a two-register operand. 4014- ``R``: Print the high-order register of a register-pair, or the high-order 4015 register of a two-register operand. 4016- ``H``: Print the second register of a register-pair. (On a big-endian system, 4017 ``H`` is equivalent to ``Q``, and on little-endian system, ``H`` is equivalent 4018 to ``R``.) 4019 4020 .. FIXME: H doesn't currently support printing the second register 4021 of a two-register operand. 4022 4023- ``e``: Print the low doubleword register of a NEON quad register. 4024- ``f``: Print the high doubleword register of a NEON quad register. 4025- ``m``: Print the base register of a memory operand without the ``[`` and ``]`` 4026 adornment. 4027 4028Hexagon: 4029 4030- ``L``: Print the second register of a two-register operand. Requires that it 4031 has been allocated consecutively to the first. 4032 4033 .. FIXME: why is it restricted to consecutive ones? And there's 4034 nothing that ensures that happens, is there? 4035 4036- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise 4037 nothing. Used to print 'addi' vs 'add' instructions. 4038 4039MSP430: 4040 4041No additional modifiers. 4042 4043MIPS: 4044 4045- ``X``: Print an immediate integer as hexadecimal 4046- ``x``: Print the low 16 bits of an immediate integer as hexadecimal. 4047- ``d``: Print an immediate integer as decimal. 4048- ``m``: Subtract one and print an immediate integer as decimal. 4049- ``z``: Print $0 if an immediate zero, otherwise print normally. 4050- ``L``: Print the low-order register of a two-register operand, or prints the 4051 address of the low-order word of a double-word memory operand. 4052 4053 .. FIXME: L seems to be missing memory operand support. 4054 4055- ``M``: Print the high-order register of a two-register operand, or prints the 4056 address of the high-order word of a double-word memory operand. 4057 4058 .. FIXME: M seems to be missing memory operand support. 4059 4060- ``D``: Print the second register of a two-register operand, or prints the 4061 second word of a double-word memory operand. (On a big-endian system, ``D`` is 4062 equivalent to ``L``, and on little-endian system, ``D`` is equivalent to 4063 ``M``.) 4064- ``w``: No effect. Provided for compatibility with GCC which requires this 4065 modifier in order to print MSA registers (``W0-W31``) with the ``f`` 4066 constraint. 4067 4068NVPTX: 4069 4070- ``r``: No effect. 4071 4072PowerPC: 4073 4074- ``L``: Print the second register of a two-register operand. Requires that it 4075 has been allocated consecutively to the first. 4076 4077 .. FIXME: why is it restricted to consecutive ones? And there's 4078 nothing that ensures that happens, is there? 4079 4080- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise 4081 nothing. Used to print 'addi' vs 'add' instructions. 4082- ``y``: For a memory operand, prints formatter for a two-register X-form 4083 instruction. (Currently always prints ``r0,OPERAND``). 4084- ``U``: Prints 'u' if the memory operand is an update form, and nothing 4085 otherwise. (NOTE: LLVM does not support update form, so this will currently 4086 always print nothing) 4087- ``X``: Prints 'x' if the memory operand is an indexed form. (NOTE: LLVM does 4088 not support indexed form, so this will currently always print nothing) 4089 4090Sparc: 4091 4092- ``r``: No effect. 4093 4094SystemZ: 4095 4096SystemZ implements only ``n``, and does *not* support any of the other 4097target-independent modifiers. 4098 4099X86: 4100 4101- ``c``: Print an unadorned integer or symbol name. (The latter is 4102 target-specific behavior for this typically target-independent modifier). 4103- ``A``: Print a register name with a '``*``' before it. 4104- ``b``: Print an 8-bit register name (e.g. ``al``); do nothing on a memory 4105 operand. 4106- ``h``: Print the upper 8-bit register name (e.g. ``ah``); do nothing on a 4107 memory operand. 4108- ``w``: Print the 16-bit register name (e.g. ``ax``); do nothing on a memory 4109 operand. 4110- ``k``: Print the 32-bit register name (e.g. ``eax``); do nothing on a memory 4111 operand. 4112- ``q``: Print the 64-bit register name (e.g. ``rax``), if 64-bit registers are 4113 available, otherwise the 32-bit register name; do nothing on a memory operand. 4114- ``n``: Negate and print an unadorned integer, or, for operands other than an 4115 immediate integer (e.g. a relocatable symbol expression), print a '-' before 4116 the operand. (The behavior for relocatable symbol expressions is a 4117 target-specific behavior for this typically target-independent modifier) 4118- ``H``: Print a memory reference with additional offset +8. 4119- ``P``: Print a memory reference or operand for use as the argument of a call 4120 instruction. (E.g. omit ``(rip)``, even though it's PC-relative.) 4121 4122XCore: 4123 4124No additional modifiers. 4125 4126 4127Inline Asm Metadata 4128^^^^^^^^^^^^^^^^^^^ 4129 4130The call instructions that wrap inline asm nodes may have a 4131"``!srcloc``" MDNode attached to it that contains a list of constant 4132integers. If present, the code generator will use the integer as the 4133location cookie value when report errors through the ``LLVMContext`` 4134error reporting mechanisms. This allows a front-end to correlate backend 4135errors that occur with inline asm back to the source code that produced 4136it. For example: 4137 4138.. code-block:: llvm 4139 4140 call void asm sideeffect "something bad", ""(), !srcloc !42 4141 ... 4142 !42 = !{ i32 1234567 } 4143 4144It is up to the front-end to make sense of the magic numbers it places 4145in the IR. If the MDNode contains multiple constants, the code generator 4146will use the one that corresponds to the line of the asm that the error 4147occurs on. 4148 4149.. _metadata: 4150 4151Metadata 4152======== 4153 4154LLVM IR allows metadata to be attached to instructions in the program 4155that can convey extra information about the code to the optimizers and 4156code generator. One example application of metadata is source-level 4157debug information. There are two metadata primitives: strings and nodes. 4158 4159Metadata does not have a type, and is not a value. If referenced from a 4160``call`` instruction, it uses the ``metadata`` type. 4161 4162All metadata are identified in syntax by a exclamation point ('``!``'). 4163 4164.. _metadata-string: 4165 4166Metadata Nodes and Metadata Strings 4167----------------------------------- 4168 4169A metadata string is a string surrounded by double quotes. It can 4170contain any character by escaping non-printable characters with 4171"``\xx``" where "``xx``" is the two digit hex code. For example: 4172"``!"test\00"``". 4173 4174Metadata nodes are represented with notation similar to structure 4175constants (a comma separated list of elements, surrounded by braces and 4176preceded by an exclamation point). Metadata nodes can have any values as 4177their operand. For example: 4178 4179.. code-block:: llvm 4180 4181 !{ !"test\00", i32 10} 4182 4183Metadata nodes that aren't uniqued use the ``distinct`` keyword. For example: 4184 4185.. code-block:: text 4186 4187 !0 = distinct !{!"test\00", i32 10} 4188 4189``distinct`` nodes are useful when nodes shouldn't be merged based on their 4190content. They can also occur when transformations cause uniquing collisions 4191when metadata operands change. 4192 4193A :ref:`named metadata <namedmetadatastructure>` is a collection of 4194metadata nodes, which can be looked up in the module symbol table. For 4195example: 4196 4197.. code-block:: llvm 4198 4199 !foo = !{!4, !3} 4200 4201Metadata can be used as function arguments. Here the ``llvm.dbg.value`` 4202intrinsic is using three metadata arguments: 4203 4204.. code-block:: llvm 4205 4206 call void @llvm.dbg.value(metadata !24, metadata !25, metadata !26) 4207 4208Metadata can be attached to an instruction. Here metadata ``!21`` is attached 4209to the ``add`` instruction using the ``!dbg`` identifier: 4210 4211.. code-block:: llvm 4212 4213 %indvar.next = add i64 %indvar, 1, !dbg !21 4214 4215Metadata can also be attached to a function or a global variable. Here metadata 4216``!22`` is attached to the ``f1`` and ``f2 functions, and the globals ``g1`` 4217and ``g2`` using the ``!dbg`` identifier: 4218 4219.. code-block:: llvm 4220 4221 declare !dbg !22 void @f1() 4222 define void @f2() !dbg !22 { 4223 ret void 4224 } 4225 4226 @g1 = global i32 0, !dbg !22 4227 @g2 = external global i32, !dbg !22 4228 4229A transformation is required to drop any metadata attachment that it does not 4230know or know it can't preserve. Currently there is an exception for metadata 4231attachment to globals for ``!type`` and ``!absolute_symbol`` which can't be 4232unconditionally dropped unless the global is itself deleted. 4233 4234Metadata attached to a module using named metadata may not be dropped, with 4235the exception of debug metadata (named metadata with the name ``!llvm.dbg.*``). 4236 4237More information about specific metadata nodes recognized by the 4238optimizers and code generator is found below. 4239 4240.. _specialized-metadata: 4241 4242Specialized Metadata Nodes 4243^^^^^^^^^^^^^^^^^^^^^^^^^^ 4244 4245Specialized metadata nodes are custom data structures in metadata (as opposed 4246to generic tuples). Their fields are labelled, and can be specified in any 4247order. 4248 4249These aren't inherently debug info centric, but currently all the specialized 4250metadata nodes are related to debug info. 4251 4252.. _DICompileUnit: 4253 4254DICompileUnit 4255""""""""""""" 4256 4257``DICompileUnit`` nodes represent a compile unit. The ``enums:``, 4258``retainedTypes:``, ``globals:``, ``imports:`` and ``macros:`` fields are tuples 4259containing the debug info to be emitted along with the compile unit, regardless 4260of code optimizations (some nodes are only emitted if there are references to 4261them from instructions). The ``debugInfoForProfiling:`` field is a boolean 4262indicating whether or not line-table discriminators are updated to provide 4263more-accurate debug info for profiling results. 4264 4265.. code-block:: text 4266 4267 !0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang", 4268 isOptimized: true, flags: "-O2", runtimeVersion: 2, 4269 splitDebugFilename: "abc.debug", emissionKind: FullDebug, 4270 enums: !2, retainedTypes: !3, globals: !4, imports: !5, 4271 macros: !6, dwoId: 0x0abcd) 4272 4273Compile unit descriptors provide the root scope for objects declared in a 4274specific compilation unit. File descriptors are defined using this scope. These 4275descriptors are collected by a named metadata node ``!llvm.dbg.cu``. They keep 4276track of global variables, type information, and imported entities (declarations 4277and namespaces). 4278 4279.. _DIFile: 4280 4281DIFile 4282"""""" 4283 4284``DIFile`` nodes represent files. The ``filename:`` can include slashes. 4285 4286.. code-block:: none 4287 4288 !0 = !DIFile(filename: "path/to/file", directory: "/path/to/dir", 4289 checksumkind: CSK_MD5, 4290 checksum: "000102030405060708090a0b0c0d0e0f") 4291 4292Files are sometimes used in ``scope:`` fields, and are the only valid target 4293for ``file:`` fields. 4294Valid values for ``checksumkind:`` field are: {CSK_None, CSK_MD5, CSK_SHA1} 4295 4296.. _DIBasicType: 4297 4298DIBasicType 4299""""""""""" 4300 4301``DIBasicType`` nodes represent primitive types, such as ``int``, ``bool`` and 4302``float``. ``tag:`` defaults to ``DW_TAG_base_type``. 4303 4304.. code-block:: text 4305 4306 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8, 4307 encoding: DW_ATE_unsigned_char) 4308 !1 = !DIBasicType(tag: DW_TAG_unspecified_type, name: "decltype(nullptr)") 4309 4310The ``encoding:`` describes the details of the type. Usually it's one of the 4311following: 4312 4313.. code-block:: text 4314 4315 DW_ATE_address = 1 4316 DW_ATE_boolean = 2 4317 DW_ATE_float = 4 4318 DW_ATE_signed = 5 4319 DW_ATE_signed_char = 6 4320 DW_ATE_unsigned = 7 4321 DW_ATE_unsigned_char = 8 4322 4323.. _DISubroutineType: 4324 4325DISubroutineType 4326"""""""""""""""" 4327 4328``DISubroutineType`` nodes represent subroutine types. Their ``types:`` field 4329refers to a tuple; the first operand is the return type, while the rest are the 4330types of the formal arguments in order. If the first operand is ``null``, that 4331represents a function with no return value (such as ``void foo() {}`` in C++). 4332 4333.. code-block:: text 4334 4335 !0 = !BasicType(name: "int", size: 32, align: 32, DW_ATE_signed) 4336 !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char) 4337 !2 = !DISubroutineType(types: !{null, !0, !1}) ; void (int, char) 4338 4339.. _DIDerivedType: 4340 4341DIDerivedType 4342""""""""""""" 4343 4344``DIDerivedType`` nodes represent types derived from other types, such as 4345qualified types. 4346 4347.. code-block:: text 4348 4349 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8, 4350 encoding: DW_ATE_unsigned_char) 4351 !1 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !0, size: 32, 4352 align: 32) 4353 4354The following ``tag:`` values are valid: 4355 4356.. code-block:: text 4357 4358 DW_TAG_member = 13 4359 DW_TAG_pointer_type = 15 4360 DW_TAG_reference_type = 16 4361 DW_TAG_typedef = 22 4362 DW_TAG_inheritance = 28 4363 DW_TAG_ptr_to_member_type = 31 4364 DW_TAG_const_type = 38 4365 DW_TAG_friend = 42 4366 DW_TAG_volatile_type = 53 4367 DW_TAG_restrict_type = 55 4368 DW_TAG_atomic_type = 71 4369 4370.. _DIDerivedTypeMember: 4371 4372``DW_TAG_member`` is used to define a member of a :ref:`composite type 4373<DICompositeType>`. The type of the member is the ``baseType:``. The 4374``offset:`` is the member's bit offset. If the composite type has an ODR 4375``identifier:`` and does not set ``flags: DIFwdDecl``, then the member is 4376uniqued based only on its ``name:`` and ``scope:``. 4377 4378``DW_TAG_inheritance`` and ``DW_TAG_friend`` are used in the ``elements:`` 4379field of :ref:`composite types <DICompositeType>` to describe parents and 4380friends. 4381 4382``DW_TAG_typedef`` is used to provide a name for the ``baseType:``. 4383 4384``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``, 4385``DW_TAG_volatile_type``, ``DW_TAG_restrict_type`` and ``DW_TAG_atomic_type`` 4386are used to qualify the ``baseType:``. 4387 4388Note that the ``void *`` type is expressed as a type derived from NULL. 4389 4390.. _DICompositeType: 4391 4392DICompositeType 4393""""""""""""""" 4394 4395``DICompositeType`` nodes represent types composed of other types, like 4396structures and unions. ``elements:`` points to a tuple of the composed types. 4397 4398If the source language supports ODR, the ``identifier:`` field gives the unique 4399identifier used for type merging between modules. When specified, 4400:ref:`subprogram declarations <DISubprogramDeclaration>` and :ref:`member 4401derived types <DIDerivedTypeMember>` that reference the ODR-type in their 4402``scope:`` change uniquing rules. 4403 4404For a given ``identifier:``, there should only be a single composite type that 4405does not have ``flags: DIFlagFwdDecl`` set. LLVM tools that link modules 4406together will unique such definitions at parse time via the ``identifier:`` 4407field, even if the nodes are ``distinct``. 4408 4409.. code-block:: text 4410 4411 !0 = !DIEnumerator(name: "SixKind", value: 7) 4412 !1 = !DIEnumerator(name: "SevenKind", value: 7) 4413 !2 = !DIEnumerator(name: "NegEightKind", value: -8) 4414 !3 = !DICompositeType(tag: DW_TAG_enumeration_type, name: "Enum", file: !12, 4415 line: 2, size: 32, align: 32, identifier: "_M4Enum", 4416 elements: !{!0, !1, !2}) 4417 4418The following ``tag:`` values are valid: 4419 4420.. code-block:: text 4421 4422 DW_TAG_array_type = 1 4423 DW_TAG_class_type = 2 4424 DW_TAG_enumeration_type = 4 4425 DW_TAG_structure_type = 19 4426 DW_TAG_union_type = 23 4427 4428For ``DW_TAG_array_type``, the ``elements:`` should be :ref:`subrange 4429descriptors <DISubrange>`, each representing the range of subscripts at that 4430level of indexing. The ``DIFlagVector`` flag to ``flags:`` indicates that an 4431array type is a native packed vector. 4432 4433For ``DW_TAG_enumeration_type``, the ``elements:`` should be :ref:`enumerator 4434descriptors <DIEnumerator>`, each representing the definition of an enumeration 4435value for the set. All enumeration type descriptors are collected in the 4436``enums:`` field of the :ref:`compile unit <DICompileUnit>`. 4437 4438For ``DW_TAG_structure_type``, ``DW_TAG_class_type``, and 4439``DW_TAG_union_type``, the ``elements:`` should be :ref:`derived types 4440<DIDerivedType>` with ``tag: DW_TAG_member``, ``tag: DW_TAG_inheritance``, or 4441``tag: DW_TAG_friend``; or :ref:`subprograms <DISubprogram>` with 4442``isDefinition: false``. 4443 4444.. _DISubrange: 4445 4446DISubrange 4447"""""""""" 4448 4449``DISubrange`` nodes are the elements for ``DW_TAG_array_type`` variants of 4450:ref:`DICompositeType`. 4451 4452- ``count: -1`` indicates an empty array. 4453- ``count: !9`` describes the count with a :ref:`DILocalVariable`. 4454- ``count: !11`` describes the count with a :ref:`DIGlobalVariable`. 4455 4456.. code-block:: text 4457 4458 !0 = !DISubrange(count: 5, lowerBound: 0) ; array counting from 0 4459 !1 = !DISubrange(count: 5, lowerBound: 1) ; array counting from 1 4460 !2 = !DISubrange(count: -1) ; empty array. 4461 4462 ; Scopes used in rest of example 4463 !6 = !DIFile(filename: "vla.c", directory: "/path/to/file") 4464 !7 = distinct !DICompileUnit(language: DW_LANG_C99, file: !6) 4465 !8 = distinct !DISubprogram(name: "foo", scope: !7, file: !6, line: 5) 4466 4467 ; Use of local variable as count value 4468 !9 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed) 4469 !10 = !DILocalVariable(name: "count", scope: !8, file: !6, line: 42, type: !9) 4470 !11 = !DISubrange(count: !10, lowerBound: 0) 4471 4472 ; Use of global variable as count value 4473 !12 = !DIGlobalVariable(name: "count", scope: !8, file: !6, line: 22, type: !9) 4474 !13 = !DISubrange(count: !12, lowerBound: 0) 4475 4476.. _DIEnumerator: 4477 4478DIEnumerator 4479"""""""""""" 4480 4481``DIEnumerator`` nodes are the elements for ``DW_TAG_enumeration_type`` 4482variants of :ref:`DICompositeType`. 4483 4484.. code-block:: text 4485 4486 !0 = !DIEnumerator(name: "SixKind", value: 7) 4487 !1 = !DIEnumerator(name: "SevenKind", value: 7) 4488 !2 = !DIEnumerator(name: "NegEightKind", value: -8) 4489 4490DITemplateTypeParameter 4491""""""""""""""""""""""" 4492 4493``DITemplateTypeParameter`` nodes represent type parameters to generic source 4494language constructs. They are used (optionally) in :ref:`DICompositeType` and 4495:ref:`DISubprogram` ``templateParams:`` fields. 4496 4497.. code-block:: text 4498 4499 !0 = !DITemplateTypeParameter(name: "Ty", type: !1) 4500 4501DITemplateValueParameter 4502"""""""""""""""""""""""" 4503 4504``DITemplateValueParameter`` nodes represent value parameters to generic source 4505language constructs. ``tag:`` defaults to ``DW_TAG_template_value_parameter``, 4506but if specified can also be set to ``DW_TAG_GNU_template_template_param`` or 4507``DW_TAG_GNU_template_param_pack``. They are used (optionally) in 4508:ref:`DICompositeType` and :ref:`DISubprogram` ``templateParams:`` fields. 4509 4510.. code-block:: text 4511 4512 !0 = !DITemplateValueParameter(name: "Ty", type: !1, value: i32 7) 4513 4514DINamespace 4515""""""""""" 4516 4517``DINamespace`` nodes represent namespaces in the source language. 4518 4519.. code-block:: text 4520 4521 !0 = !DINamespace(name: "myawesomeproject", scope: !1, file: !2, line: 7) 4522 4523.. _DIGlobalVariable: 4524 4525DIGlobalVariable 4526"""""""""""""""" 4527 4528``DIGlobalVariable`` nodes represent global variables in the source language. 4529 4530.. code-block:: text 4531 4532 @foo = global i32, !dbg !0 4533 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression()) 4534 !1 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !2, 4535 file: !3, line: 7, type: !4, isLocal: true, 4536 isDefinition: false, declaration: !5) 4537 4538 4539DIGlobalVariableExpression 4540"""""""""""""""""""""""""" 4541 4542``DIGlobalVariableExpression`` nodes tie a :ref:`DIGlobalVariable` together 4543with a :ref:`DIExpression`. 4544 4545.. code-block:: text 4546 4547 @lower = global i32, !dbg !0 4548 @upper = global i32, !dbg !1 4549 !0 = !DIGlobalVariableExpression( 4550 var: !2, 4551 expr: !DIExpression(DW_OP_LLVM_fragment, 0, 32) 4552 ) 4553 !1 = !DIGlobalVariableExpression( 4554 var: !2, 4555 expr: !DIExpression(DW_OP_LLVM_fragment, 32, 32) 4556 ) 4557 !2 = !DIGlobalVariable(name: "split64", linkageName: "split64", scope: !3, 4558 file: !4, line: 8, type: !5, declaration: !6) 4559 4560All global variable expressions should be referenced by the `globals:` field of 4561a :ref:`compile unit <DICompileUnit>`. 4562 4563.. _DISubprogram: 4564 4565DISubprogram 4566"""""""""""" 4567 4568``DISubprogram`` nodes represent functions from the source language. A 4569``DISubprogram`` may be attached to a function definition using ``!dbg`` 4570metadata. The ``variables:`` field points at :ref:`variables <DILocalVariable>` 4571that must be retained, even if their IR counterparts are optimized out of 4572the IR. The ``type:`` field must point at an :ref:`DISubroutineType`. 4573 4574.. _DISubprogramDeclaration: 4575 4576When ``isDefinition: false``, subprograms describe a declaration in the type 4577tree as opposed to a definition of a function. If the scope is a composite 4578type with an ODR ``identifier:`` and that does not set ``flags: DIFwdDecl``, 4579then the subprogram declaration is uniqued based only on its ``linkageName:`` 4580and ``scope:``. 4581 4582.. code-block:: text 4583 4584 define void @_Z3foov() !dbg !0 { 4585 ... 4586 } 4587 4588 !0 = distinct !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1, 4589 file: !2, line: 7, type: !3, isLocal: true, 4590 isDefinition: true, scopeLine: 8, 4591 containingType: !4, 4592 virtuality: DW_VIRTUALITY_pure_virtual, 4593 virtualIndex: 10, flags: DIFlagPrototyped, 4594 isOptimized: true, unit: !5, templateParams: !6, 4595 declaration: !7, variables: !8, thrownTypes: !9) 4596 4597.. _DILexicalBlock: 4598 4599DILexicalBlock 4600"""""""""""""" 4601 4602``DILexicalBlock`` nodes describe nested blocks within a :ref:`subprogram 4603<DISubprogram>`. The line number and column numbers are used to distinguish 4604two lexical blocks at same depth. They are valid targets for ``scope:`` 4605fields. 4606 4607.. code-block:: text 4608 4609 !0 = distinct !DILexicalBlock(scope: !1, file: !2, line: 7, column: 35) 4610 4611Usually lexical blocks are ``distinct`` to prevent node merging based on 4612operands. 4613 4614.. _DILexicalBlockFile: 4615 4616DILexicalBlockFile 4617"""""""""""""""""" 4618 4619``DILexicalBlockFile`` nodes are used to discriminate between sections of a 4620:ref:`lexical block <DILexicalBlock>`. The ``file:`` field can be changed to 4621indicate textual inclusion, or the ``discriminator:`` field can be used to 4622discriminate between control flow within a single block in the source language. 4623 4624.. code-block:: text 4625 4626 !0 = !DILexicalBlock(scope: !3, file: !4, line: 7, column: 35) 4627 !1 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 0) 4628 !2 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 1) 4629 4630.. _DILocation: 4631 4632DILocation 4633"""""""""" 4634 4635``DILocation`` nodes represent source debug locations. The ``scope:`` field is 4636mandatory, and points at an :ref:`DILexicalBlockFile`, an 4637:ref:`DILexicalBlock`, or an :ref:`DISubprogram`. 4638 4639.. code-block:: text 4640 4641 !0 = !DILocation(line: 2900, column: 42, scope: !1, inlinedAt: !2) 4642 4643.. _DILocalVariable: 4644 4645DILocalVariable 4646""""""""""""""" 4647 4648``DILocalVariable`` nodes represent local variables in the source language. If 4649the ``arg:`` field is set to non-zero, then this variable is a subprogram 4650parameter, and it will be included in the ``variables:`` field of its 4651:ref:`DISubprogram`. 4652 4653.. code-block:: text 4654 4655 !0 = !DILocalVariable(name: "this", arg: 1, scope: !3, file: !2, line: 7, 4656 type: !3, flags: DIFlagArtificial) 4657 !1 = !DILocalVariable(name: "x", arg: 2, scope: !4, file: !2, line: 7, 4658 type: !3) 4659 !2 = !DILocalVariable(name: "y", scope: !5, file: !2, line: 7, type: !3) 4660 4661.. _DIExpression: 4662 4663DIExpression 4664"""""""""""" 4665 4666``DIExpression`` nodes represent expressions that are inspired by the DWARF 4667expression language. They are used in :ref:`debug intrinsics<dbg_intrinsics>` 4668(such as ``llvm.dbg.declare`` and ``llvm.dbg.value``) to describe how the 4669referenced LLVM variable relates to the source language variable. Debug 4670intrinsics are interpreted left-to-right: start by pushing the value/address 4671operand of the intrinsic onto a stack, then repeatedly push and evaluate 4672opcodes from the DIExpression until the final variable description is produced. 4673 4674The current supported opcode vocabulary is limited: 4675 4676- ``DW_OP_deref`` dereferences the top of the expression stack. 4677- ``DW_OP_plus`` pops the last two entries from the expression stack, adds 4678 them together and appends the result to the expression stack. 4679- ``DW_OP_minus`` pops the last two entries from the expression stack, subtracts 4680 the last entry from the second last entry and appends the result to the 4681 expression stack. 4682- ``DW_OP_plus_uconst, 93`` adds ``93`` to the working expression. 4683- ``DW_OP_LLVM_fragment, 16, 8`` specifies the offset and size (``16`` and ``8`` 4684 here, respectively) of the variable fragment from the working expression. Note 4685 that contrary to DW_OP_bit_piece, the offset is describing the location 4686 within the described source variable. 4687- ``DW_OP_LLVM_convert, 16, DW_ATE_signed`` specifies a bit size and encoding 4688 (``16`` and ``DW_ATE_signed`` here, respectively) to which the top of the 4689 expression stack is to be converted. Maps into a ``DW_OP_convert`` operation 4690 that references a base type constructed from the supplied values. 4691- ``DW_OP_swap`` swaps top two stack entries. 4692- ``DW_OP_xderef`` provides extended dereference mechanism. The entry at the top 4693 of the stack is treated as an address. The second stack entry is treated as an 4694 address space identifier. 4695- ``DW_OP_stack_value`` marks a constant value. 4696 4697DWARF specifies three kinds of simple location descriptions: Register, memory, 4698and implicit location descriptions. Note that a location description is 4699defined over certain ranges of a program, i.e the location of a variable may 4700change over the course of the program. Register and memory location 4701descriptions describe the *concrete location* of a source variable (in the 4702sense that a debugger might modify its value), whereas *implicit locations* 4703describe merely the actual *value* of a source variable which might not exist 4704in registers or in memory (see ``DW_OP_stack_value``). 4705 4706A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect 4707value (the address) of a source variable. The first operand of the intrinsic 4708must be an address of some kind. A DIExpression attached to the intrinsic 4709refines this address to produce a concrete location for the source variable. 4710 4711A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable. 4712The first operand of the intrinsic may be a direct or indirect value. A 4713DIExpresion attached to the intrinsic refines the first operand to produce a 4714direct value. For example, if the first operand is an indirect value, it may be 4715necessary to insert ``DW_OP_deref`` into the DIExpresion in order to produce a 4716valid debug intrinsic. 4717 4718.. note:: 4719 4720 A DIExpression is interpreted in the same way regardless of which kind of 4721 debug intrinsic it's attached to. 4722 4723.. code-block:: text 4724 4725 !0 = !DIExpression(DW_OP_deref) 4726 !1 = !DIExpression(DW_OP_plus_uconst, 3) 4727 !1 = !DIExpression(DW_OP_constu, 3, DW_OP_plus) 4728 !2 = !DIExpression(DW_OP_bit_piece, 3, 7) 4729 !3 = !DIExpression(DW_OP_deref, DW_OP_constu, 3, DW_OP_plus, DW_OP_LLVM_fragment, 3, 7) 4730 !4 = !DIExpression(DW_OP_constu, 2, DW_OP_swap, DW_OP_xderef) 4731 !5 = !DIExpression(DW_OP_constu, 42, DW_OP_stack_value) 4732 4733DIObjCProperty 4734"""""""""""""" 4735 4736``DIObjCProperty`` nodes represent Objective-C property nodes. 4737 4738.. code-block:: text 4739 4740 !3 = !DIObjCProperty(name: "foo", file: !1, line: 7, setter: "setFoo", 4741 getter: "getFoo", attributes: 7, type: !2) 4742 4743DIImportedEntity 4744"""""""""""""""" 4745 4746``DIImportedEntity`` nodes represent entities (such as modules) imported into a 4747compile unit. 4748 4749.. code-block:: text 4750 4751 !2 = !DIImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0, 4752 entity: !1, line: 7) 4753 4754DIMacro 4755""""""" 4756 4757``DIMacro`` nodes represent definition or undefinition of a macro identifiers. 4758The ``name:`` field is the macro identifier, followed by macro parameters when 4759defining a function-like macro, and the ``value`` field is the token-string 4760used to expand the macro identifier. 4761 4762.. code-block:: text 4763 4764 !2 = !DIMacro(macinfo: DW_MACINFO_define, line: 7, name: "foo(x)", 4765 value: "((x) + 1)") 4766 !3 = !DIMacro(macinfo: DW_MACINFO_undef, line: 30, name: "foo") 4767 4768DIMacroFile 4769""""""""""" 4770 4771``DIMacroFile`` nodes represent inclusion of source files. 4772The ``nodes:`` field is a list of ``DIMacro`` and ``DIMacroFile`` nodes that 4773appear in the included source file. 4774 4775.. code-block:: text 4776 4777 !2 = !DIMacroFile(macinfo: DW_MACINFO_start_file, line: 7, file: !2, 4778 nodes: !3) 4779 4780'``tbaa``' Metadata 4781^^^^^^^^^^^^^^^^^^^ 4782 4783In LLVM IR, memory does not have types, so LLVM's own type system is not 4784suitable for doing type based alias analysis (TBAA). Instead, metadata is 4785added to the IR to describe a type system of a higher level language. This 4786can be used to implement C/C++ strict type aliasing rules, but it can also 4787be used to implement custom alias analysis behavior for other languages. 4788 4789This description of LLVM's TBAA system is broken into two parts: 4790:ref:`Semantics<tbaa_node_semantics>` talks about high level issues, and 4791:ref:`Representation<tbaa_node_representation>` talks about the metadata 4792encoding of various entities. 4793 4794It is always possible to trace any TBAA node to a "root" TBAA node (details 4795in the :ref:`Representation<tbaa_node_representation>` section). TBAA 4796nodes with different roots have an unknown aliasing relationship, and LLVM 4797conservatively infers ``MayAlias`` between them. The rules mentioned in 4798this section only pertain to TBAA nodes living under the same root. 4799 4800.. _tbaa_node_semantics: 4801 4802Semantics 4803""""""""" 4804 4805The TBAA metadata system, referred to as "struct path TBAA" (not to be 4806confused with ``tbaa.struct``), consists of the following high level 4807concepts: *Type Descriptors*, further subdivided into scalar type 4808descriptors and struct type descriptors; and *Access Tags*. 4809 4810**Type descriptors** describe the type system of the higher level language 4811being compiled. **Scalar type descriptors** describe types that do not 4812contain other types. Each scalar type has a parent type, which must also 4813be a scalar type or the TBAA root. Via this parent relation, scalar types 4814within a TBAA root form a tree. **Struct type descriptors** denote types 4815that contain a sequence of other type descriptors, at known offsets. These 4816contained type descriptors can either be struct type descriptors themselves 4817or scalar type descriptors. 4818 4819**Access tags** are metadata nodes attached to load and store instructions. 4820Access tags use type descriptors to describe the *location* being accessed 4821in terms of the type system of the higher level language. Access tags are 4822tuples consisting of a base type, an access type and an offset. The base 4823type is a scalar type descriptor or a struct type descriptor, the access 4824type is a scalar type descriptor, and the offset is a constant integer. 4825 4826The access tag ``(BaseTy, AccessTy, Offset)`` can describe one of two 4827things: 4828 4829 * If ``BaseTy`` is a struct type, the tag describes a memory access (load 4830 or store) of a value of type ``AccessTy`` contained in the struct type 4831 ``BaseTy`` at offset ``Offset``. 4832 4833 * If ``BaseTy`` is a scalar type, ``Offset`` must be 0 and ``BaseTy`` and 4834 ``AccessTy`` must be the same; and the access tag describes a scalar 4835 access with scalar type ``AccessTy``. 4836 4837We first define an ``ImmediateParent`` relation on ``(BaseTy, Offset)`` 4838tuples this way: 4839 4840 * If ``BaseTy`` is a scalar type then ``ImmediateParent(BaseTy, 0)`` is 4841 ``(ParentTy, 0)`` where ``ParentTy`` is the parent of the scalar type as 4842 described in the TBAA metadata. ``ImmediateParent(BaseTy, Offset)`` is 4843 undefined if ``Offset`` is non-zero. 4844 4845 * If ``BaseTy`` is a struct type then ``ImmediateParent(BaseTy, Offset)`` 4846 is ``(NewTy, NewOffset)`` where ``NewTy`` is the type contained in 4847 ``BaseTy`` at offset ``Offset`` and ``NewOffset`` is ``Offset`` adjusted 4848 to be relative within that inner type. 4849 4850A memory access with an access tag ``(BaseTy1, AccessTy1, Offset1)`` 4851aliases a memory access with an access tag ``(BaseTy2, AccessTy2, 4852Offset2)`` if either ``(BaseTy1, Offset1)`` is reachable from ``(Base2, 4853Offset2)`` via the ``Parent`` relation or vice versa. 4854 4855As a concrete example, the type descriptor graph for the following program 4856 4857.. code-block:: c 4858 4859 struct Inner { 4860 int i; // offset 0 4861 float f; // offset 4 4862 }; 4863 4864 struct Outer { 4865 float f; // offset 0 4866 double d; // offset 4 4867 struct Inner inner_a; // offset 12 4868 }; 4869 4870 void f(struct Outer* outer, struct Inner* inner, float* f, int* i, char* c) { 4871 outer->f = 0; // tag0: (OuterStructTy, FloatScalarTy, 0) 4872 outer->inner_a.i = 0; // tag1: (OuterStructTy, IntScalarTy, 12) 4873 outer->inner_a.f = 0.0; // tag2: (OuterStructTy, FloatScalarTy, 16) 4874 *f = 0.0; // tag3: (FloatScalarTy, FloatScalarTy, 0) 4875 } 4876 4877is (note that in C and C++, ``char`` can be used to access any arbitrary 4878type): 4879 4880.. code-block:: text 4881 4882 Root = "TBAA Root" 4883 CharScalarTy = ("char", Root, 0) 4884 FloatScalarTy = ("float", CharScalarTy, 0) 4885 DoubleScalarTy = ("double", CharScalarTy, 0) 4886 IntScalarTy = ("int", CharScalarTy, 0) 4887 InnerStructTy = {"Inner" (IntScalarTy, 0), (FloatScalarTy, 4)} 4888 OuterStructTy = {"Outer", (FloatScalarTy, 0), (DoubleScalarTy, 4), 4889 (InnerStructTy, 12)} 4890 4891 4892with (e.g.) ``ImmediateParent(OuterStructTy, 12)`` = ``(InnerStructTy, 48930)``, ``ImmediateParent(InnerStructTy, 0)`` = ``(IntScalarTy, 0)``, and 4894``ImmediateParent(IntScalarTy, 0)`` = ``(CharScalarTy, 0)``. 4895 4896.. _tbaa_node_representation: 4897 4898Representation 4899"""""""""""""" 4900 4901The root node of a TBAA type hierarchy is an ``MDNode`` with 0 operands or 4902with exactly one ``MDString`` operand. 4903 4904Scalar type descriptors are represented as an ``MDNode`` s with two 4905operands. The first operand is an ``MDString`` denoting the name of the 4906struct type. LLVM does not assign meaning to the value of this operand, it 4907only cares about it being an ``MDString``. The second operand is an 4908``MDNode`` which points to the parent for said scalar type descriptor, 4909which is either another scalar type descriptor or the TBAA root. Scalar 4910type descriptors can have an optional third argument, but that must be the 4911constant integer zero. 4912 4913Struct type descriptors are represented as ``MDNode`` s with an odd number 4914of operands greater than 1. The first operand is an ``MDString`` denoting 4915the name of the struct type. Like in scalar type descriptors the actual 4916value of this name operand is irrelevant to LLVM. After the name operand, 4917the struct type descriptors have a sequence of alternating ``MDNode`` and 4918``ConstantInt`` operands. With N starting from 1, the 2N - 1 th operand, 4919an ``MDNode``, denotes a contained field, and the 2N th operand, a 4920``ConstantInt``, is the offset of the said contained field. The offsets 4921must be in non-decreasing order. 4922 4923Access tags are represented as ``MDNode`` s with either 3 or 4 operands. 4924The first operand is an ``MDNode`` pointing to the node representing the 4925base type. The second operand is an ``MDNode`` pointing to the node 4926representing the access type. The third operand is a ``ConstantInt`` that 4927states the offset of the access. If a fourth field is present, it must be 4928a ``ConstantInt`` valued at 0 or 1. If it is 1 then the access tag states 4929that the location being accessed is "constant" (meaning 4930``pointsToConstantMemory`` should return true; see `other useful 4931AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_). The TBAA root of 4932the access type and the base type of an access tag must be the same, and 4933that is the TBAA root of the access tag. 4934 4935'``tbaa.struct``' Metadata 4936^^^^^^^^^^^^^^^^^^^^^^^^^^ 4937 4938The :ref:`llvm.memcpy <int_memcpy>` is often used to implement 4939aggregate assignment operations in C and similar languages, however it 4940is defined to copy a contiguous region of memory, which is more than 4941strictly necessary for aggregate types which contain holes due to 4942padding. Also, it doesn't contain any TBAA information about the fields 4943of the aggregate. 4944 4945``!tbaa.struct`` metadata can describe which memory subregions in a 4946memcpy are padding and what the TBAA tags of the struct are. 4947 4948The current metadata format is very simple. ``!tbaa.struct`` metadata 4949nodes are a list of operands which are in conceptual groups of three. 4950For each group of three, the first operand gives the byte offset of a 4951field in bytes, the second gives its size in bytes, and the third gives 4952its tbaa tag. e.g.: 4953 4954.. code-block:: llvm 4955 4956 !4 = !{ i64 0, i64 4, !1, i64 8, i64 4, !2 } 4957 4958This describes a struct with two fields. The first is at offset 0 bytes 4959with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes 4960and has size 4 bytes and has tbaa tag !2. 4961 4962Note that the fields need not be contiguous. In this example, there is a 49634 byte gap between the two fields. This gap represents padding which 4964does not carry useful data and need not be preserved. 4965 4966'``noalias``' and '``alias.scope``' Metadata 4967^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4968 4969``noalias`` and ``alias.scope`` metadata provide the ability to specify generic 4970noalias memory-access sets. This means that some collection of memory access 4971instructions (loads, stores, memory-accessing calls, etc.) that carry 4972``noalias`` metadata can specifically be specified not to alias with some other 4973collection of memory access instructions that carry ``alias.scope`` metadata. 4974Each type of metadata specifies a list of scopes where each scope has an id and 4975a domain. 4976 4977When evaluating an aliasing query, if for some domain, the set 4978of scopes with that domain in one instruction's ``alias.scope`` list is a 4979subset of (or equal to) the set of scopes for that domain in another 4980instruction's ``noalias`` list, then the two memory accesses are assumed not to 4981alias. 4982 4983Because scopes in one domain don't affect scopes in other domains, separate 4984domains can be used to compose multiple independent noalias sets. This is 4985used for example during inlining. As the noalias function parameters are 4986turned into noalias scope metadata, a new domain is used every time the 4987function is inlined. 4988 4989The metadata identifying each domain is itself a list containing one or two 4990entries. The first entry is the name of the domain. Note that if the name is a 4991string then it can be combined across functions and translation units. A 4992self-reference can be used to create globally unique domain names. A 4993descriptive string may optionally be provided as a second list entry. 4994 4995The metadata identifying each scope is also itself a list containing two or 4996three entries. The first entry is the name of the scope. Note that if the name 4997is a string then it can be combined across functions and translation units. A 4998self-reference can be used to create globally unique scope names. A metadata 4999reference to the scope's domain is the second entry. A descriptive string may 5000optionally be provided as a third list entry. 5001 5002For example, 5003 5004.. code-block:: llvm 5005 5006 ; Two scope domains: 5007 !0 = !{!0} 5008 !1 = !{!1} 5009 5010 ; Some scopes in these domains: 5011 !2 = !{!2, !0} 5012 !3 = !{!3, !0} 5013 !4 = !{!4, !1} 5014 5015 ; Some scope lists: 5016 !5 = !{!4} ; A list containing only scope !4 5017 !6 = !{!4, !3, !2} 5018 !7 = !{!3} 5019 5020 ; These two instructions don't alias: 5021 %0 = load float, float* %c, align 4, !alias.scope !5 5022 store float %0, float* %arrayidx.i, align 4, !noalias !5 5023 5024 ; These two instructions also don't alias (for domain !1, the set of scopes 5025 ; in the !alias.scope equals that in the !noalias list): 5026 %2 = load float, float* %c, align 4, !alias.scope !5 5027 store float %2, float* %arrayidx.i2, align 4, !noalias !6 5028 5029 ; These two instructions may alias (for domain !0, the set of scopes in 5030 ; the !noalias list is not a superset of, or equal to, the scopes in the 5031 ; !alias.scope list): 5032 %2 = load float, float* %c, align 4, !alias.scope !6 5033 store float %0, float* %arrayidx.i, align 4, !noalias !7 5034 5035'``fpmath``' Metadata 5036^^^^^^^^^^^^^^^^^^^^^ 5037 5038``fpmath`` metadata may be attached to any instruction of floating-point 5039type. It can be used to express the maximum acceptable error in the 5040result of that instruction, in ULPs, thus potentially allowing the 5041compiler to use a more efficient but less accurate method of computing 5042it. ULP is defined as follows: 5043 5044 If ``x`` is a real number that lies between two finite consecutive 5045 floating-point numbers ``a`` and ``b``, without being equal to one 5046 of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the 5047 distance between the two non-equal finite floating-point numbers 5048 nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``. 5049 5050The metadata node shall consist of a single positive float type number 5051representing the maximum relative error, for example: 5052 5053.. code-block:: llvm 5054 5055 !0 = !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs 5056 5057.. _range-metadata: 5058 5059'``range``' Metadata 5060^^^^^^^^^^^^^^^^^^^^ 5061 5062``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of 5063integer types. It expresses the possible ranges the loaded value or the value 5064returned by the called function at this call site is in. If the loaded or 5065returned value is not in the specified range, the behavior is undefined. The 5066ranges are represented with a flattened list of integers. The loaded value or 5067the value returned is known to be in the union of the ranges defined by each 5068consecutive pair. Each pair has the following properties: 5069 5070- The type must match the type loaded by the instruction. 5071- The pair ``a,b`` represents the range ``[a,b)``. 5072- Both ``a`` and ``b`` are constants. 5073- The range is allowed to wrap. 5074- The range should not represent the full or empty set. That is, 5075 ``a!=b``. 5076 5077In addition, the pairs must be in signed order of the lower bound and 5078they must be non-contiguous. 5079 5080Examples: 5081 5082.. code-block:: llvm 5083 5084 %a = load i8, i8* %x, align 1, !range !0 ; Can only be 0 or 1 5085 %b = load i8, i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1 5086 %c = call i8 @foo(), !range !2 ; Can only be 0, 1, 3, 4 or 5 5087 %d = invoke i8 @bar() to label %cont 5088 unwind label %lpad, !range !3 ; Can only be -2, -1, 3, 4 or 5 5089 ... 5090 !0 = !{ i8 0, i8 2 } 5091 !1 = !{ i8 255, i8 2 } 5092 !2 = !{ i8 0, i8 2, i8 3, i8 6 } 5093 !3 = !{ i8 -2, i8 0, i8 3, i8 6 } 5094 5095'``absolute_symbol``' Metadata 5096^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5097 5098``absolute_symbol`` metadata may be attached to a global variable 5099declaration. It marks the declaration as a reference to an absolute symbol, 5100which causes the backend to use absolute relocations for the symbol even 5101in position independent code, and expresses the possible ranges that the 5102global variable's *address* (not its value) is in, in the same format as 5103``range`` metadata, with the extension that the pair ``all-ones,all-ones`` 5104may be used to represent the full set. 5105 5106Example (assuming 64-bit pointers): 5107 5108.. code-block:: llvm 5109 5110 @a = external global i8, !absolute_symbol !0 ; Absolute symbol in range [0,256) 5111 @b = external global i8, !absolute_symbol !1 ; Absolute symbol in range [0,2^64) 5112 5113 ... 5114 !0 = !{ i64 0, i64 256 } 5115 !1 = !{ i64 -1, i64 -1 } 5116 5117'``callees``' Metadata 5118^^^^^^^^^^^^^^^^^^^^^^ 5119 5120``callees`` metadata may be attached to indirect call sites. If ``callees`` 5121metadata is attached to a call site, and any callee is not among the set of 5122functions provided by the metadata, the behavior is undefined. The intent of 5123this metadata is to facilitate optimizations such as indirect-call promotion. 5124For example, in the code below, the call instruction may only target the 5125``add`` or ``sub`` functions: 5126 5127.. code-block:: llvm 5128 5129 %result = call i64 %binop(i64 %x, i64 %y), !callees !0 5130 5131 ... 5132 !0 = !{i64 (i64, i64)* @add, i64 (i64, i64)* @sub} 5133 5134'``callback``' Metadata 5135^^^^^^^^^^^^^^^^^^^^^^^ 5136 5137``callback`` metadata may be attached to a function declaration, or definition. 5138(Call sites are excluded only due to the lack of a use case.) For ease of 5139exposition, we'll refer to the function annotated w/ metadata as a broker 5140function. The metadata describes how the arguments of a call to the broker are 5141in turn passed to the callback function specified by the metadata. Thus, the 5142``callback`` metadata provides a partial description of a call site inside the 5143broker function with regards to the arguments of a call to the broker. The only 5144semantic restriction on the broker function itself is that it is not allowed to 5145inspect or modify arguments referenced in the ``callback`` metadata as 5146pass-through to the callback function. 5147 5148The broker is not required to actually invoke the callback function at runtime. 5149However, the assumptions about not inspecting or modifying arguments that would 5150be passed to the specified callback function still hold, even if the callback 5151function is not dynamically invoked. The broker is allowed to invoke the 5152callback function more than once per invocation of the broker. The broker is 5153also allowed to invoke (directly or indirectly) the function passed as a 5154callback through another use. Finally, the broker is also allowed to relay the 5155callback callee invocation to a different thread. 5156 5157The metadata is structured as follows: At the outer level, ``callback`` 5158metadata is a list of ``callback`` encodings. Each encoding starts with a 5159constant ``i64`` which describes the argument position of the callback function 5160in the call to the broker. The following elements, except the last, describe 5161what arguments are passed to the callback function. Each element is again an 5162``i64`` constant identifying the argument of the broker that is passed through, 5163or ``i64 -1`` to indicate an unknown or inspected argument. The order in which 5164they are listed has to be the same in which they are passed to the callback 5165callee. The last element of the encoding is a boolean which specifies how 5166variadic arguments of the broker are handled. If it is true, all variadic 5167arguments of the broker are passed through to the callback function *after* the 5168arguments encoded explicitly before. 5169 5170In the code below, the ``pthread_create`` function is marked as a broker 5171through the ``!callback !1`` metadata. In the example, there is only one 5172callback encoding, namely ``!2``, associated with the broker. This encoding 5173identifies the callback function as the second argument of the broker (``i64 51742``) and the sole argument of the callback function as the third one of the 5175broker function (``i64 3``). 5176 5177.. FIXME why does the llvm-sphinx-docs builder give a highlighting 5178 error if the below is set to highlight as 'llvm', despite that we 5179 have misc.highlighting_failure set? 5180 5181.. code-block:: text 5182 5183 declare !callback !1 dso_local i32 @pthread_create(i64*, %union.pthread_attr_t*, i8* (i8*)*, i8*) 5184 5185 ... 5186 !2 = !{i64 2, i64 3, i1 false} 5187 !1 = !{!2} 5188 5189Another example is shown below. The callback callee is the second argument of 5190the ``__kmpc_fork_call`` function (``i64 2``). The callee is given two unknown 5191values (each identified by a ``i64 -1``) and afterwards all 5192variadic arguments that are passed to the ``__kmpc_fork_call`` call (due to the 5193final ``i1 true``). 5194 5195.. FIXME why does the llvm-sphinx-docs builder give a highlighting 5196 error if the below is set to highlight as 'llvm', despite that we 5197 have misc.highlighting_failure set? 5198 5199.. code-block:: text 5200 5201 declare !callback !0 dso_local void @__kmpc_fork_call(%struct.ident_t*, i32, void (i32*, i32*, ...)*, ...) 5202 5203 ... 5204 !1 = !{i64 2, i64 -1, i64 -1, i1 true} 5205 !0 = !{!1} 5206 5207 5208'``unpredictable``' Metadata 5209^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5210 5211``unpredictable`` metadata may be attached to any branch or switch 5212instruction. It can be used to express the unpredictability of control 5213flow. Similar to the llvm.expect intrinsic, it may be used to alter 5214optimizations related to compare and branch instructions. The metadata 5215is treated as a boolean value; if it exists, it signals that the branch 5216or switch that it is attached to is completely unpredictable. 5217 5218.. _llvm.loop: 5219 5220'``llvm.loop``' 5221^^^^^^^^^^^^^^^ 5222 5223It is sometimes useful to attach information to loop constructs. Currently, 5224loop metadata is implemented as metadata attached to the branch instruction 5225in the loop latch block. This type of metadata refer to a metadata node that is 5226guaranteed to be separate for each loop. The loop identifier metadata is 5227specified with the name ``llvm.loop``. 5228 5229The loop identifier metadata is implemented using a metadata that refers to 5230itself to avoid merging it with any other identifier metadata, e.g., 5231during module linkage or function inlining. That is, each loop should refer 5232to their own identification metadata even if they reside in separate functions. 5233The following example contains loop identifier metadata for two separate loop 5234constructs: 5235 5236.. code-block:: llvm 5237 5238 !0 = !{!0} 5239 !1 = !{!1} 5240 5241The loop identifier metadata can be used to specify additional 5242per-loop metadata. Any operands after the first operand can be treated 5243as user-defined metadata. For example the ``llvm.loop.unroll.count`` 5244suggests an unroll factor to the loop unroller: 5245 5246.. code-block:: llvm 5247 5248 br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0 5249 ... 5250 !0 = !{!0, !1} 5251 !1 = !{!"llvm.loop.unroll.count", i32 4} 5252 5253'``llvm.loop.disable_nonforced``' 5254^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5255 5256This metadata disables all optional loop transformations unless 5257explicitly instructed using other transformation metdata such as 5258``llvm.loop.unroll.enable``. That is, no heuristic will try to determine 5259whether a transformation is profitable. The purpose is to avoid that the 5260loop is transformed to a different loop before an explicitly requested 5261(forced) transformation is applied. For instance, loop fusion can make 5262other transformations impossible. Mandatory loop canonicalizations such 5263as loop rotation are still applied. 5264 5265It is recommended to use this metadata in addition to any llvm.loop.* 5266transformation directive. Also, any loop should have at most one 5267directive applied to it (and a sequence of transformations built using 5268followup-attributes). Otherwise, which transformation will be applied 5269depends on implementation details such as the pass pipeline order. 5270 5271See :ref:`transformation-metadata` for details. 5272 5273'``llvm.loop.vectorize``' and '``llvm.loop.interleave``' 5274^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5275 5276Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are 5277used to control per-loop vectorization and interleaving parameters such as 5278vectorization width and interleave count. These metadata should be used in 5279conjunction with ``llvm.loop`` loop identification metadata. The 5280``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only 5281optimization hints and the optimizer will only interleave and vectorize loops if 5282it believes it is safe to do so. The ``llvm.loop.parallel_accesses`` metadata 5283which contains information about loop-carried memory dependencies can be helpful 5284in determining the safety of these transformations. 5285 5286'``llvm.loop.interleave.count``' Metadata 5287^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5288 5289This metadata suggests an interleave count to the loop interleaver. 5290The first operand is the string ``llvm.loop.interleave.count`` and the 5291second operand is an integer specifying the interleave count. For 5292example: 5293 5294.. code-block:: llvm 5295 5296 !0 = !{!"llvm.loop.interleave.count", i32 4} 5297 5298Note that setting ``llvm.loop.interleave.count`` to 1 disables interleaving 5299multiple iterations of the loop. If ``llvm.loop.interleave.count`` is set to 0 5300then the interleave count will be determined automatically. 5301 5302'``llvm.loop.vectorize.enable``' Metadata 5303^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5304 5305This metadata selectively enables or disables vectorization for the loop. The 5306first operand is the string ``llvm.loop.vectorize.enable`` and the second operand 5307is a bit. If the bit operand value is 1 vectorization is enabled. A value of 53080 disables vectorization: 5309 5310.. code-block:: llvm 5311 5312 !0 = !{!"llvm.loop.vectorize.enable", i1 0} 5313 !1 = !{!"llvm.loop.vectorize.enable", i1 1} 5314 5315'``llvm.loop.vectorize.width``' Metadata 5316^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5317 5318This metadata sets the target width of the vectorizer. The first 5319operand is the string ``llvm.loop.vectorize.width`` and the second 5320operand is an integer specifying the width. For example: 5321 5322.. code-block:: llvm 5323 5324 !0 = !{!"llvm.loop.vectorize.width", i32 4} 5325 5326Note that setting ``llvm.loop.vectorize.width`` to 1 disables 5327vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to 53280 or if the loop does not have this metadata the width will be 5329determined automatically. 5330 5331'``llvm.loop.vectorize.followup_vectorized``' Metadata 5332^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5333 5334This metadata defines which loop attributes the vectorized loop will 5335have. See :ref:`transformation-metadata` for details. 5336 5337'``llvm.loop.vectorize.followup_epilogue``' Metadata 5338^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5339 5340This metadata defines which loop attributes the epilogue will have. The 5341epilogue is not vectorized and is executed when either the vectorized 5342loop is not known to preserve semantics (because e.g., it processes two 5343arrays that are found to alias by a runtime check) or for the last 5344iterations that do not fill a complete set of vector lanes. See 5345:ref:`Transformation Metadata <transformation-metadata>` for details. 5346 5347'``llvm.loop.vectorize.followup_all``' Metadata 5348^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5349 5350Attributes in the metadata will be added to both the vectorized and 5351epilogue loop. 5352See :ref:`Transformation Metadata <transformation-metadata>` for details. 5353 5354'``llvm.loop.unroll``' 5355^^^^^^^^^^^^^^^^^^^^^^ 5356 5357Metadata prefixed with ``llvm.loop.unroll`` are loop unrolling 5358optimization hints such as the unroll factor. ``llvm.loop.unroll`` 5359metadata should be used in conjunction with ``llvm.loop`` loop 5360identification metadata. The ``llvm.loop.unroll`` metadata are only 5361optimization hints and the unrolling will only be performed if the 5362optimizer believes it is safe to do so. 5363 5364'``llvm.loop.unroll.count``' Metadata 5365^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5366 5367This metadata suggests an unroll factor to the loop unroller. The 5368first operand is the string ``llvm.loop.unroll.count`` and the second 5369operand is a positive integer specifying the unroll factor. For 5370example: 5371 5372.. code-block:: llvm 5373 5374 !0 = !{!"llvm.loop.unroll.count", i32 4} 5375 5376If the trip count of the loop is less than the unroll count the loop 5377will be partially unrolled. 5378 5379'``llvm.loop.unroll.disable``' Metadata 5380^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5381 5382This metadata disables loop unrolling. The metadata has a single operand 5383which is the string ``llvm.loop.unroll.disable``. For example: 5384 5385.. code-block:: llvm 5386 5387 !0 = !{!"llvm.loop.unroll.disable"} 5388 5389'``llvm.loop.unroll.runtime.disable``' Metadata 5390^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5391 5392This metadata disables runtime loop unrolling. The metadata has a single 5393operand which is the string ``llvm.loop.unroll.runtime.disable``. For example: 5394 5395.. code-block:: llvm 5396 5397 !0 = !{!"llvm.loop.unroll.runtime.disable"} 5398 5399'``llvm.loop.unroll.enable``' Metadata 5400^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5401 5402This metadata suggests that the loop should be fully unrolled if the trip count 5403is known at compile time and partially unrolled if the trip count is not known 5404at compile time. The metadata has a single operand which is the string 5405``llvm.loop.unroll.enable``. For example: 5406 5407.. code-block:: llvm 5408 5409 !0 = !{!"llvm.loop.unroll.enable"} 5410 5411'``llvm.loop.unroll.full``' Metadata 5412^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5413 5414This metadata suggests that the loop should be unrolled fully. The 5415metadata has a single operand which is the string ``llvm.loop.unroll.full``. 5416For example: 5417 5418.. code-block:: llvm 5419 5420 !0 = !{!"llvm.loop.unroll.full"} 5421 5422'``llvm.loop.unroll.followup``' Metadata 5423^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5424 5425This metadata defines which loop attributes the unrolled loop will have. 5426See :ref:`Transformation Metadata <transformation-metadata>` for details. 5427 5428'``llvm.loop.unroll.followup_remainder``' Metadata 5429^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5430 5431This metadata defines which loop attributes the remainder loop after 5432partial/runtime unrolling will have. See 5433:ref:`Transformation Metadata <transformation-metadata>` for details. 5434 5435'``llvm.loop.unroll_and_jam``' 5436^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5437 5438This metadata is treated very similarly to the ``llvm.loop.unroll`` metadata 5439above, but affect the unroll and jam pass. In addition any loop with 5440``llvm.loop.unroll`` metadata but no ``llvm.loop.unroll_and_jam`` metadata will 5441disable unroll and jam (so ``llvm.loop.unroll`` metadata will be left to the 5442unroller, plus ``llvm.loop.unroll.disable`` metadata will disable unroll and jam 5443too.) 5444 5445The metadata for unroll and jam otherwise is the same as for ``unroll``. 5446``llvm.loop.unroll_and_jam.enable``, ``llvm.loop.unroll_and_jam.disable`` and 5447``llvm.loop.unroll_and_jam.count`` do the same as for unroll. 5448``llvm.loop.unroll_and_jam.full`` is not supported. Again these are only hints 5449and the normal safety checks will still be performed. 5450 5451'``llvm.loop.unroll_and_jam.count``' Metadata 5452^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5453 5454This metadata suggests an unroll and jam factor to use, similarly to 5455``llvm.loop.unroll.count``. The first operand is the string 5456``llvm.loop.unroll_and_jam.count`` and the second operand is a positive integer 5457specifying the unroll factor. For example: 5458 5459.. code-block:: llvm 5460 5461 !0 = !{!"llvm.loop.unroll_and_jam.count", i32 4} 5462 5463If the trip count of the loop is less than the unroll count the loop 5464will be partially unroll and jammed. 5465 5466'``llvm.loop.unroll_and_jam.disable``' Metadata 5467^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5468 5469This metadata disables loop unroll and jamming. The metadata has a single 5470operand which is the string ``llvm.loop.unroll_and_jam.disable``. For example: 5471 5472.. code-block:: llvm 5473 5474 !0 = !{!"llvm.loop.unroll_and_jam.disable"} 5475 5476'``llvm.loop.unroll_and_jam.enable``' Metadata 5477^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5478 5479This metadata suggests that the loop should be fully unroll and jammed if the 5480trip count is known at compile time and partially unrolled if the trip count is 5481not known at compile time. The metadata has a single operand which is the 5482string ``llvm.loop.unroll_and_jam.enable``. For example: 5483 5484.. code-block:: llvm 5485 5486 !0 = !{!"llvm.loop.unroll_and_jam.enable"} 5487 5488'``llvm.loop.unroll_and_jam.followup_outer``' Metadata 5489^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5490 5491This metadata defines which loop attributes the outer unrolled loop will 5492have. See :ref:`Transformation Metadata <transformation-metadata>` for 5493details. 5494 5495'``llvm.loop.unroll_and_jam.followup_inner``' Metadata 5496^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5497 5498This metadata defines which loop attributes the inner jammed loop will 5499have. See :ref:`Transformation Metadata <transformation-metadata>` for 5500details. 5501 5502'``llvm.loop.unroll_and_jam.followup_remainder_outer``' Metadata 5503^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5504 5505This metadata defines which attributes the epilogue of the outer loop 5506will have. This loop is usually unrolled, meaning there is no such 5507loop. This attribute will be ignored in this case. See 5508:ref:`Transformation Metadata <transformation-metadata>` for details. 5509 5510'``llvm.loop.unroll_and_jam.followup_remainder_inner``' Metadata 5511^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5512 5513This metadata defines which attributes the inner loop of the epilogue 5514will have. The outer epilogue will usually be unrolled, meaning there 5515can be multiple inner remainder loops. See 5516:ref:`Transformation Metadata <transformation-metadata>` for details. 5517 5518'``llvm.loop.unroll_and_jam.followup_all``' Metadata 5519^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5520 5521Attributes specified in the metadata is added to all 5522``llvm.loop.unroll_and_jam.*`` loops. See 5523:ref:`Transformation Metadata <transformation-metadata>` for details. 5524 5525'``llvm.loop.licm_versioning.disable``' Metadata 5526^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5527 5528This metadata indicates that the loop should not be versioned for the purpose 5529of enabling loop-invariant code motion (LICM). The metadata has a single operand 5530which is the string ``llvm.loop.licm_versioning.disable``. For example: 5531 5532.. code-block:: llvm 5533 5534 !0 = !{!"llvm.loop.licm_versioning.disable"} 5535 5536'``llvm.loop.distribute.enable``' Metadata 5537^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5538 5539Loop distribution allows splitting a loop into multiple loops. Currently, 5540this is only performed if the entire loop cannot be vectorized due to unsafe 5541memory dependencies. The transformation will attempt to isolate the unsafe 5542dependencies into their own loop. 5543 5544This metadata can be used to selectively enable or disable distribution of the 5545loop. The first operand is the string ``llvm.loop.distribute.enable`` and the 5546second operand is a bit. If the bit operand value is 1 distribution is 5547enabled. A value of 0 disables distribution: 5548 5549.. code-block:: llvm 5550 5551 !0 = !{!"llvm.loop.distribute.enable", i1 0} 5552 !1 = !{!"llvm.loop.distribute.enable", i1 1} 5553 5554This metadata should be used in conjunction with ``llvm.loop`` loop 5555identification metadata. 5556 5557'``llvm.loop.distribute.followup_coincident``' Metadata 5558^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5559 5560This metadata defines which attributes extracted loops with no cyclic 5561dependencies will have (i.e. can be vectorized). See 5562:ref:`Transformation Metadata <transformation-metadata>` for details. 5563 5564'``llvm.loop.distribute.followup_sequential``' Metadata 5565^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5566 5567This metadata defines which attributes the isolated loops with unsafe 5568memory dependencies will have. See 5569:ref:`Transformation Metadata <transformation-metadata>` for details. 5570 5571'``llvm.loop.distribute.followup_fallback``' Metadata 5572^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5573 5574If loop versioning is necessary, this metadata defined the attributes 5575the non-distributed fallback version will have. See 5576:ref:`Transformation Metadata <transformation-metadata>` for details. 5577 5578'``llvm.loop.distribute.followup_all``' Metadata 5579^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5580 5581Thes attributes in this metdata is added to all followup loops of the 5582loop distribution pass. See 5583:ref:`Transformation Metadata <transformation-metadata>` for details. 5584 5585'``llvm.access.group``' Metadata 5586^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5587 5588``llvm.access.group`` metadata can be attached to any instruction that 5589potentially accesses memory. It can point to a single distinct metadata 5590node, which we call access group. This node represents all memory access 5591instructions referring to it via ``llvm.access.group``. When an 5592instruction belongs to multiple access groups, it can also point to a 5593list of accesses groups, illustrated by the following example. 5594 5595.. code-block:: llvm 5596 5597 %val = load i32, i32* %arrayidx, !llvm.access.group !0 5598 ... 5599 !0 = !{!1, !2} 5600 !1 = distinct !{} 5601 !2 = distinct !{} 5602 5603It is illegal for the list node to be empty since it might be confused 5604with an access group. 5605 5606The access group metadata node must be 'distinct' to avoid collapsing 5607multiple access groups by content. A access group metadata node must 5608always be empty which can be used to distinguish an access group 5609metadata node from a list of access groups. Being empty avoids the 5610situation that the content must be updated which, because metadata is 5611immutable by design, would required finding and updating all references 5612to the access group node. 5613 5614The access group can be used to refer to a memory access instruction 5615without pointing to it directly (which is not possible in global 5616metadata). Currently, the only metadata making use of it is 5617``llvm.loop.parallel_accesses``. 5618 5619'``llvm.loop.parallel_accesses``' Metadata 5620^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5621 5622The ``llvm.loop.parallel_accesses`` metadata refers to one or more 5623access group metadata nodes (see ``llvm.access.group``). It denotes that 5624no loop-carried memory dependence exist between it and other instructions 5625in the loop with this metadata. 5626 5627Let ``m1`` and ``m2`` be two instructions that both have the 5628``llvm.access.group`` metadata to the access group ``g1``, respectively 5629``g2`` (which might be identical). If a loop contains both access groups 5630in its ``llvm.loop.parallel_accesses`` metadata, then the compiler can 5631assume that there is no dependency between ``m1`` and ``m2`` carried by 5632this loop. Instructions that belong to multiple access groups are 5633considered having this property if at least one of the access groups 5634matches the ``llvm.loop.parallel_accesses`` list. 5635 5636If all memory-accessing instructions in a loop have 5637``llvm.loop.parallel_accesses`` metadata that refers to that loop, then the 5638loop has no loop carried memory dependences and is considered to be a 5639parallel loop. 5640 5641Note that if not all memory access instructions belong to an access 5642group referred to by ``llvm.loop.parallel_accesses``, then the loop must 5643not be considered trivially parallel. Additional 5644memory dependence analysis is required to make that determination. As a fail 5645safe mechanism, this causes loops that were originally parallel to be considered 5646sequential (if optimization passes that are unaware of the parallel semantics 5647insert new memory instructions into the loop body). 5648 5649Example of a loop that is considered parallel due to its correct use of 5650both ``llvm.access.group`` and ``llvm.loop.parallel_accesses`` 5651metadata types. 5652 5653.. code-block:: llvm 5654 5655 for.body: 5656 ... 5657 %val0 = load i32, i32* %arrayidx, !llvm.access.group !1 5658 ... 5659 store i32 %val0, i32* %arrayidx1, !llvm.access.group !1 5660 ... 5661 br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0 5662 5663 for.end: 5664 ... 5665 !0 = distinct !{!0, !{!"llvm.loop.parallel_accesses", !1}} 5666 !1 = distinct !{} 5667 5668It is also possible to have nested parallel loops: 5669 5670.. code-block:: llvm 5671 5672 outer.for.body: 5673 ... 5674 %val1 = load i32, i32* %arrayidx3, !llvm.access.group !4 5675 ... 5676 br label %inner.for.body 5677 5678 inner.for.body: 5679 ... 5680 %val0 = load i32, i32* %arrayidx1, !llvm.access.group !3 5681 ... 5682 store i32 %val0, i32* %arrayidx2, !llvm.access.group !3 5683 ... 5684 br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1 5685 5686 inner.for.end: 5687 ... 5688 store i32 %val1, i32* %arrayidx4, !llvm.access.group !4 5689 ... 5690 br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2 5691 5692 outer.for.end: ; preds = %for.body 5693 ... 5694 !1 = distinct !{!1, !{!"llvm.loop.parallel_accesses", !3}} ; metadata for the inner loop 5695 !2 = distinct !{!2, !{!"llvm.loop.parallel_accesses", !3, !4}} ; metadata for the outer loop 5696 !3 = distinct !{} ; access group for instructions in the inner loop (which are implicitly contained in outer loop as well) 5697 !4 = distinct !{} ; access group for instructions in the outer, but not the inner loop 5698 5699'``irr_loop``' Metadata 5700^^^^^^^^^^^^^^^^^^^^^^^ 5701 5702``irr_loop`` metadata may be attached to the terminator instruction of a basic 5703block that's an irreducible loop header (note that an irreducible loop has more 5704than once header basic blocks.) If ``irr_loop`` metadata is attached to the 5705terminator instruction of a basic block that is not really an irreducible loop 5706header, the behavior is undefined. The intent of this metadata is to improve the 5707accuracy of the block frequency propagation. For example, in the code below, the 5708block ``header0`` may have a loop header weight (relative to the other headers of 5709the irreducible loop) of 100: 5710 5711.. code-block:: llvm 5712 5713 header0: 5714 ... 5715 br i1 %cmp, label %t1, label %t2, !irr_loop !0 5716 5717 ... 5718 !0 = !{"loop_header_weight", i64 100} 5719 5720Irreducible loop header weights are typically based on profile data. 5721 5722'``invariant.group``' Metadata 5723^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5724 5725The experimental ``invariant.group`` metadata may be attached to 5726``load``/``store`` instructions referencing a single metadata with no entries. 5727The existence of the ``invariant.group`` metadata on the instruction tells 5728the optimizer that every ``load`` and ``store`` to the same pointer operand 5729can be assumed to load or store the same 5730value (but see the ``llvm.launder.invariant.group`` intrinsic which affects 5731when two pointers are considered the same). Pointers returned by bitcast or 5732getelementptr with only zero indices are considered the same. 5733 5734Examples: 5735 5736.. code-block:: llvm 5737 5738 @unknownPtr = external global i8 5739 ... 5740 %ptr = alloca i8 5741 store i8 42, i8* %ptr, !invariant.group !0 5742 call void @foo(i8* %ptr) 5743 5744 %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change 5745 call void @foo(i8* %ptr) 5746 5747 %newPtr = call i8* @getPointer(i8* %ptr) 5748 %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr 5749 5750 %unknownValue = load i8, i8* @unknownPtr 5751 store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42 5752 5753 call void @foo(i8* %ptr) 5754 %newPtr2 = call i8* @llvm.launder.invariant.group(i8* %ptr) 5755 %d = load i8, i8* %newPtr2, !invariant.group !0 ; Can't step through launder.invariant.group to get value of %ptr 5756 5757 ... 5758 declare void @foo(i8*) 5759 declare i8* @getPointer(i8*) 5760 declare i8* @llvm.launder.invariant.group(i8*) 5761 5762 !0 = !{} 5763 5764The invariant.group metadata must be dropped when replacing one pointer by 5765another based on aliasing information. This is because invariant.group is tied 5766to the SSA value of the pointer operand. 5767 5768.. code-block:: llvm 5769 5770 %v = load i8, i8* %x, !invariant.group !0 5771 ; if %x mustalias %y then we can replace the above instruction with 5772 %v = load i8, i8* %y 5773 5774Note that this is an experimental feature, which means that its semantics might 5775change in the future. 5776 5777'``type``' Metadata 5778^^^^^^^^^^^^^^^^^^^ 5779 5780See :doc:`TypeMetadata`. 5781 5782'``associated``' Metadata 5783^^^^^^^^^^^^^^^^^^^^^^^^^ 5784 5785The ``associated`` metadata may be attached to a global object 5786declaration with a single argument that references another global object. 5787 5788This metadata prevents discarding of the global object in linker GC 5789unless the referenced object is also discarded. The linker support for 5790this feature is spotty. For best compatibility, globals carrying this 5791metadata may also: 5792 5793- Be in a comdat with the referenced global. 5794- Be in @llvm.compiler.used. 5795- Have an explicit section with a name which is a valid C identifier. 5796 5797It does not have any effect on non-ELF targets. 5798 5799Example: 5800 5801.. code-block:: text 5802 5803 $a = comdat any 5804 @a = global i32 1, comdat $a 5805 @b = internal global i32 2, comdat $a, section "abc", !associated !0 5806 !0 = !{i32* @a} 5807 5808 5809'``prof``' Metadata 5810^^^^^^^^^^^^^^^^^^^ 5811 5812The ``prof`` metadata is used to record profile data in the IR. 5813The first operand of the metadata node indicates the profile metadata 5814type. There are currently 3 types: 5815:ref:`branch_weights<prof_node_branch_weights>`, 5816:ref:`function_entry_count<prof_node_function_entry_count>`, and 5817:ref:`VP<prof_node_VP>`. 5818 5819.. _prof_node_branch_weights: 5820 5821branch_weights 5822"""""""""""""" 5823 5824Branch weight metadata attached to a branch, select, switch or call instruction 5825represents the likeliness of the associated branch being taken. 5826For more information, see :doc:`BranchWeightMetadata`. 5827 5828.. _prof_node_function_entry_count: 5829 5830function_entry_count 5831"""""""""""""""""""" 5832 5833Function entry count metadata can be attached to function definitions 5834to record the number of times the function is called. Used with BFI 5835information, it is also used to derive the basic block profile count. 5836For more information, see :doc:`BranchWeightMetadata`. 5837 5838.. _prof_node_VP: 5839 5840VP 5841"" 5842 5843VP (value profile) metadata can be attached to instructions that have 5844value profile information. Currently this is indirect calls (where it 5845records the hottest callees) and calls to memory intrinsics such as memcpy, 5846memmove, and memset (where it records the hottest byte lengths). 5847 5848Each VP metadata node contains "VP" string, then a uint32_t value for the value 5849profiling kind, a uint64_t value for the total number of times the instruction 5850is executed, followed by uint64_t value and execution count pairs. 5851The value profiling kind is 0 for indirect call targets and 1 for memory 5852operations. For indirect call targets, each profile value is a hash 5853of the callee function name, and for memory operations each value is the 5854byte length. 5855 5856Note that the value counts do not need to add up to the total count 5857listed in the third operand (in practice only the top hottest values 5858are tracked and reported). 5859 5860Indirect call example: 5861 5862.. code-block:: llvm 5863 5864 call void %f(), !prof !1 5865 !1 = !{!"VP", i32 0, i64 1600, i64 7651369219802541373, i64 1030, i64 -4377547752858689819, i64 410} 5866 5867Note that the VP type is 0 (the second operand), which indicates this is 5868an indirect call value profile data. The third operand indicates that the 5869indirect call executed 1600 times. The 4th and 6th operands give the 5870hashes of the 2 hottest target functions' names (this is the same hash used 5871to represent function names in the profile database), and the 5th and 7th 5872operands give the execution count that each of the respective prior target 5873functions was called. 5874 5875Module Flags Metadata 5876===================== 5877 5878Information about the module as a whole is difficult to convey to LLVM's 5879subsystems. The LLVM IR isn't sufficient to transmit this information. 5880The ``llvm.module.flags`` named metadata exists in order to facilitate 5881this. These flags are in the form of key / value pairs --- much like a 5882dictionary --- making it easy for any subsystem who cares about a flag to 5883look it up. 5884 5885The ``llvm.module.flags`` metadata contains a list of metadata triplets. 5886Each triplet has the following form: 5887 5888- The first element is a *behavior* flag, which specifies the behavior 5889 when two (or more) modules are merged together, and it encounters two 5890 (or more) metadata with the same ID. The supported behaviors are 5891 described below. 5892- The second element is a metadata string that is a unique ID for the 5893 metadata. Each module may only have one flag entry for each unique ID (not 5894 including entries with the **Require** behavior). 5895- The third element is the value of the flag. 5896 5897When two (or more) modules are merged together, the resulting 5898``llvm.module.flags`` metadata is the union of the modules' flags. That is, for 5899each unique metadata ID string, there will be exactly one entry in the merged 5900modules ``llvm.module.flags`` metadata table, and the value for that entry will 5901be determined by the merge behavior flag, as described below. The only exception 5902is that entries with the *Require* behavior are always preserved. 5903 5904The following behaviors are supported: 5905 5906.. list-table:: 5907 :header-rows: 1 5908 :widths: 10 90 5909 5910 * - Value 5911 - Behavior 5912 5913 * - 1 5914 - **Error** 5915 Emits an error if two values disagree, otherwise the resulting value 5916 is that of the operands. 5917 5918 * - 2 5919 - **Warning** 5920 Emits a warning if two values disagree. The result value will be the 5921 operand for the flag from the first module being linked. 5922 5923 * - 3 5924 - **Require** 5925 Adds a requirement that another module flag be present and have a 5926 specified value after linking is performed. The value must be a 5927 metadata pair, where the first element of the pair is the ID of the 5928 module flag to be restricted, and the second element of the pair is 5929 the value the module flag should be restricted to. This behavior can 5930 be used to restrict the allowable results (via triggering of an 5931 error) of linking IDs with the **Override** behavior. 5932 5933 * - 4 5934 - **Override** 5935 Uses the specified value, regardless of the behavior or value of the 5936 other module. If both modules specify **Override**, but the values 5937 differ, an error will be emitted. 5938 5939 * - 5 5940 - **Append** 5941 Appends the two values, which are required to be metadata nodes. 5942 5943 * - 6 5944 - **AppendUnique** 5945 Appends the two values, which are required to be metadata 5946 nodes. However, duplicate entries in the second list are dropped 5947 during the append operation. 5948 5949 * - 7 5950 - **Max** 5951 Takes the max of the two values, which are required to be integers. 5952 5953It is an error for a particular unique flag ID to have multiple behaviors, 5954except in the case of **Require** (which adds restrictions on another metadata 5955value) or **Override**. 5956 5957An example of module flags: 5958 5959.. code-block:: llvm 5960 5961 !0 = !{ i32 1, !"foo", i32 1 } 5962 !1 = !{ i32 4, !"bar", i32 37 } 5963 !2 = !{ i32 2, !"qux", i32 42 } 5964 !3 = !{ i32 3, !"qux", 5965 !{ 5966 !"foo", i32 1 5967 } 5968 } 5969 !llvm.module.flags = !{ !0, !1, !2, !3 } 5970 5971- Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior 5972 if two or more ``!"foo"`` flags are seen is to emit an error if their 5973 values are not equal. 5974 5975- Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The 5976 behavior if two or more ``!"bar"`` flags are seen is to use the value 5977 '37'. 5978 5979- Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The 5980 behavior if two or more ``!"qux"`` flags are seen is to emit a 5981 warning if their values are not equal. 5982 5983- Metadata ``!3`` has the ID ``!"qux"`` and the value: 5984 5985 :: 5986 5987 !{ !"foo", i32 1 } 5988 5989 The behavior is to emit an error if the ``llvm.module.flags`` does not 5990 contain a flag with the ID ``!"foo"`` that has the value '1' after linking is 5991 performed. 5992 5993Objective-C Garbage Collection Module Flags Metadata 5994---------------------------------------------------- 5995 5996On the Mach-O platform, Objective-C stores metadata about garbage 5997collection in a special section called "image info". The metadata 5998consists of a version number and a bitmask specifying what types of 5999garbage collection are supported (if any) by the file. If two or more 6000modules are linked together their garbage collection metadata needs to 6001be merged rather than appended together. 6002 6003The Objective-C garbage collection module flags metadata consists of the 6004following key-value pairs: 6005 6006.. list-table:: 6007 :header-rows: 1 6008 :widths: 30 70 6009 6010 * - Key 6011 - Value 6012 6013 * - ``Objective-C Version`` 6014 - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2. 6015 6016 * - ``Objective-C Image Info Version`` 6017 - **[Required]** --- The version of the image info section. Currently 6018 always 0. 6019 6020 * - ``Objective-C Image Info Section`` 6021 - **[Required]** --- The section to place the metadata. Valid values are 6022 ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and 6023 ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for 6024 Objective-C ABI version 2. 6025 6026 * - ``Objective-C Garbage Collection`` 6027 - **[Required]** --- Specifies whether garbage collection is supported or 6028 not. Valid values are 0, for no garbage collection, and 2, for garbage 6029 collection supported. 6030 6031 * - ``Objective-C GC Only`` 6032 - **[Optional]** --- Specifies that only garbage collection is supported. 6033 If present, its value must be 6. This flag requires that the 6034 ``Objective-C Garbage Collection`` flag have the value 2. 6035 6036Some important flag interactions: 6037 6038- If a module with ``Objective-C Garbage Collection`` set to 0 is 6039 merged with a module with ``Objective-C Garbage Collection`` set to 6040 2, then the resulting module has the 6041 ``Objective-C Garbage Collection`` flag set to 0. 6042- A module with ``Objective-C Garbage Collection`` set to 0 cannot be 6043 merged with a module with ``Objective-C GC Only`` set to 6. 6044 6045C type width Module Flags Metadata 6046---------------------------------- 6047 6048The ARM backend emits a section into each generated object file describing the 6049options that it was compiled with (in a compiler-independent way) to prevent 6050linking incompatible objects, and to allow automatic library selection. Some 6051of these options are not visible at the IR level, namely wchar_t width and enum 6052width. 6053 6054To pass this information to the backend, these options are encoded in module 6055flags metadata, using the following key-value pairs: 6056 6057.. list-table:: 6058 :header-rows: 1 6059 :widths: 30 70 6060 6061 * - Key 6062 - Value 6063 6064 * - short_wchar 6065 - * 0 --- sizeof(wchar_t) == 4 6066 * 1 --- sizeof(wchar_t) == 2 6067 6068 * - short_enum 6069 - * 0 --- Enums are at least as large as an ``int``. 6070 * 1 --- Enums are stored in the smallest integer type which can 6071 represent all of its values. 6072 6073For example, the following metadata section specifies that the module was 6074compiled with a ``wchar_t`` width of 4 bytes, and the underlying type of an 6075enum is the smallest type which can represent all of its values:: 6076 6077 !llvm.module.flags = !{!0, !1} 6078 !0 = !{i32 1, !"short_wchar", i32 1} 6079 !1 = !{i32 1, !"short_enum", i32 0} 6080 6081Automatic Linker Flags Named Metadata 6082===================================== 6083 6084Some targets support embedding flags to the linker inside individual object 6085files. Typically this is used in conjunction with language extensions which 6086allow source files to explicitly declare the libraries they depend on, and have 6087these automatically be transmitted to the linker via object files. 6088 6089These flags are encoded in the IR using named metadata with the name 6090``!llvm.linker.options``. Each operand is expected to be a metadata node 6091which should be a list of other metadata nodes, each of which should be a 6092list of metadata strings defining linker options. 6093 6094For example, the following metadata section specifies two separate sets of 6095linker options, presumably to link against ``libz`` and the ``Cocoa`` 6096framework:: 6097 6098 !0 = !{ !"-lz" }, 6099 !1 = !{ !"-framework", !"Cocoa" } } } 6100 !llvm.linker.options = !{ !0, !1 } 6101 6102The metadata encoding as lists of lists of options, as opposed to a collapsed 6103list of options, is chosen so that the IR encoding can use multiple option 6104strings to specify e.g., a single library, while still having that specifier be 6105preserved as an atomic element that can be recognized by a target specific 6106assembly writer or object file emitter. 6107 6108Each individual option is required to be either a valid option for the target's 6109linker, or an option that is reserved by the target specific assembly writer or 6110object file emitter. No other aspect of these options is defined by the IR. 6111 6112.. _summary: 6113 6114ThinLTO Summary 6115=============== 6116 6117Compiling with `ThinLTO <https://clang.llvm.org/docs/ThinLTO.html>`_ 6118causes the building of a compact summary of the module that is emitted into 6119the bitcode. The summary is emitted into the LLVM assembly and identified 6120in syntax by a caret ('``^``'). 6121 6122The summary is parsed into a bitcode output, along with the Module 6123IR, via the "``llvm-as``" tool. Tools that parse the Module IR for the purposes 6124of optimization (e.g. "``clang -x ir``" and "``opt``"), will ignore the 6125summary entries (just as they currently ignore summary entries in a bitcode 6126input file). 6127 6128Eventually, the summary will be parsed into a ModuleSummaryIndex object under 6129the same conditions where summary index is currently built from bitcode. 6130Specifically, tools that test the Thin Link portion of a ThinLTO compile 6131(i.e. llvm-lto and llvm-lto2), or when parsing a combined index 6132for a distributed ThinLTO backend via clang's "``-fthinlto-index=<>``" flag 6133(this part is not yet implemented, use llvm-as to create a bitcode object 6134before feeding into thin link tools for now). 6135 6136There are currently 3 types of summary entries in the LLVM assembly: 6137:ref:`module paths<module_path_summary>`, 6138:ref:`global values<gv_summary>`, and 6139:ref:`type identifiers<typeid_summary>`. 6140 6141.. _module_path_summary: 6142 6143Module Path Summary Entry 6144------------------------- 6145 6146Each module path summary entry lists a module containing global values included 6147in the summary. For a single IR module there will be one such entry, but 6148in a combined summary index produced during the thin link, there will be 6149one module path entry per linked module with summary. 6150 6151Example: 6152 6153.. code-block:: text 6154 6155 ^0 = module: (path: "/path/to/file.o", hash: (2468601609, 1329373163, 1565878005, 638838075, 3148790418)) 6156 6157The ``path`` field is a string path to the bitcode file, and the ``hash`` 6158field is the 160-bit SHA-1 hash of the IR bitcode contents, used for 6159incremental builds and caching. 6160 6161.. _gv_summary: 6162 6163Global Value Summary Entry 6164-------------------------- 6165 6166Each global value summary entry corresponds to a global value defined or 6167referenced by a summarized module. 6168 6169Example: 6170 6171.. code-block:: text 6172 6173 ^4 = gv: (name: "f"[, summaries: (Summary)[, (Summary)]*]?) ; guid = 14740650423002898831 6174 6175For declarations, there will not be a summary list. For definitions, a 6176global value will contain a list of summaries, one per module containing 6177a definition. There can be multiple entries in a combined summary index 6178for symbols with weak linkage. 6179 6180Each ``Summary`` format will depend on whether the global value is a 6181:ref:`function<function_summary>`, :ref:`variable<variable_summary>`, or 6182:ref:`alias<alias_summary>`. 6183 6184.. _function_summary: 6185 6186Function Summary 6187^^^^^^^^^^^^^^^^ 6188 6189If the global value is a function, the ``Summary`` entry will look like: 6190 6191.. code-block:: text 6192 6193 function: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), insts: 2[, FuncFlags]?[, Calls]?[, TypeIdInfo]?[, Refs]? 6194 6195The ``module`` field includes the summary entry id for the module containing 6196this definition, and the ``flags`` field contains information such as 6197the linkage type, a flag indicating whether it is legal to import the 6198definition, whether it is globally live and whether the linker resolved it 6199to a local definition (the latter two are populated during the thin link). 6200The ``insts`` field contains the number of IR instructions in the function. 6201Finally, there are several optional fields: :ref:`FuncFlags<funcflags_summary>`, 6202:ref:`Calls<calls_summary>`, :ref:`TypeIdInfo<typeidinfo_summary>`, 6203:ref:`Refs<refs_summary>`. 6204 6205.. _variable_summary: 6206 6207Global Variable Summary 6208^^^^^^^^^^^^^^^^^^^^^^^ 6209 6210If the global value is a variable, the ``Summary`` entry will look like: 6211 6212.. code-block:: text 6213 6214 variable: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0)[, Refs]? 6215 6216The variable entry contains a subset of the fields in a 6217:ref:`function summary <function_summary>`, see the descriptions there. 6218 6219.. _alias_summary: 6220 6221Alias Summary 6222^^^^^^^^^^^^^ 6223 6224If the global value is an alias, the ``Summary`` entry will look like: 6225 6226.. code-block:: text 6227 6228 alias: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), aliasee: ^2) 6229 6230The ``module`` and ``flags`` fields are as described for a 6231:ref:`function summary <function_summary>`. The ``aliasee`` field 6232contains a reference to the global value summary entry of the aliasee. 6233 6234.. _funcflags_summary: 6235 6236Function Flags 6237^^^^^^^^^^^^^^ 6238 6239The optional ``FuncFlags`` field looks like: 6240 6241.. code-block:: text 6242 6243 funcFlags: (readNone: 0, readOnly: 0, noRecurse: 0, returnDoesNotAlias: 0) 6244 6245If unspecified, flags are assumed to hold the conservative ``false`` value of 6246``0``. 6247 6248.. _calls_summary: 6249 6250Calls 6251^^^^^ 6252 6253The optional ``Calls`` field looks like: 6254 6255.. code-block:: text 6256 6257 calls: ((Callee)[, (Callee)]*) 6258 6259where each ``Callee`` looks like: 6260 6261.. code-block:: text 6262 6263 callee: ^1[, hotness: None]?[, relbf: 0]? 6264 6265The ``callee`` refers to the summary entry id of the callee. At most one 6266of ``hotness`` (which can take the values ``Unknown``, ``Cold``, ``None``, 6267``Hot``, and ``Critical``), and ``relbf`` (which holds the integer 6268branch frequency relative to the entry frequency, scaled down by 2^8) 6269may be specified. The defaults are ``Unknown`` and ``0``, respectively. 6270 6271.. _refs_summary: 6272 6273Refs 6274^^^^ 6275 6276The optional ``Refs`` field looks like: 6277 6278.. code-block:: text 6279 6280 refs: ((Ref)[, (Ref)]*) 6281 6282where each ``Ref`` contains a reference to the summary id of the referenced 6283value (e.g. ``^1``). 6284 6285.. _typeidinfo_summary: 6286 6287TypeIdInfo 6288^^^^^^^^^^ 6289 6290The optional ``TypeIdInfo`` field, used for 6291`Control Flow Integrity <http://clang.llvm.org/docs/ControlFlowIntegrity.html>`_, 6292looks like: 6293 6294.. code-block:: text 6295 6296 typeIdInfo: [(TypeTests)]?[, (TypeTestAssumeVCalls)]?[, (TypeCheckedLoadVCalls)]?[, (TypeTestAssumeConstVCalls)]?[, (TypeCheckedLoadConstVCalls)]? 6297 6298These optional fields have the following forms: 6299 6300TypeTests 6301""""""""" 6302 6303.. code-block:: text 6304 6305 typeTests: (TypeIdRef[, TypeIdRef]*) 6306 6307Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>` 6308by summary id or ``GUID``. 6309 6310TypeTestAssumeVCalls 6311"""""""""""""""""""" 6312 6313.. code-block:: text 6314 6315 typeTestAssumeVCalls: (VFuncId[, VFuncId]*) 6316 6317Where each VFuncId has the format: 6318 6319.. code-block:: text 6320 6321 vFuncId: (TypeIdRef, offset: 16) 6322 6323Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>` 6324by summary id or ``GUID`` preceeded by a ``guid:`` tag. 6325 6326TypeCheckedLoadVCalls 6327""""""""""""""""""""" 6328 6329.. code-block:: text 6330 6331 typeCheckedLoadVCalls: (VFuncId[, VFuncId]*) 6332 6333Where each VFuncId has the format described for ``TypeTestAssumeVCalls``. 6334 6335TypeTestAssumeConstVCalls 6336""""""""""""""""""""""""" 6337 6338.. code-block:: text 6339 6340 typeTestAssumeConstVCalls: (ConstVCall[, ConstVCall]*) 6341 6342Where each ConstVCall has the format: 6343 6344.. code-block:: text 6345 6346 (VFuncId, args: (Arg[, Arg]*)) 6347 6348and where each VFuncId has the format described for ``TypeTestAssumeVCalls``, 6349and each Arg is an integer argument number. 6350 6351TypeCheckedLoadConstVCalls 6352"""""""""""""""""""""""""" 6353 6354.. code-block:: text 6355 6356 typeCheckedLoadConstVCalls: (ConstVCall[, ConstVCall]*) 6357 6358Where each ConstVCall has the format described for 6359``TypeTestAssumeConstVCalls``. 6360 6361.. _typeid_summary: 6362 6363Type ID Summary Entry 6364--------------------- 6365 6366Each type id summary entry corresponds to a type identifier resolution 6367which is generated during the LTO link portion of the compile when building 6368with `Control Flow Integrity <http://clang.llvm.org/docs/ControlFlowIntegrity.html>`_, 6369so these are only present in a combined summary index. 6370 6371Example: 6372 6373.. code-block:: text 6374 6375 ^4 = typeid: (name: "_ZTS1A", summary: (typeTestRes: (kind: allOnes, sizeM1BitWidth: 7[, alignLog2: 0]?[, sizeM1: 0]?[, bitMask: 0]?[, inlineBits: 0]?)[, WpdResolutions]?)) ; guid = 7004155349499253778 6376 6377The ``typeTestRes`` gives the type test resolution ``kind`` (which may 6378be ``unsat``, ``byteArray``, ``inline``, ``single``, or ``allOnes``), and 6379the ``size-1`` bit width. It is followed by optional flags, which default to 0, 6380and an optional WpdResolutions (whole program devirtualization resolution) 6381field that looks like: 6382 6383.. code-block:: text 6384 6385 wpdResolutions: ((offset: 0, WpdRes)[, (offset: 1, WpdRes)]* 6386 6387where each entry is a mapping from the given byte offset to the whole-program 6388devirtualization resolution WpdRes, that has one of the following formats: 6389 6390.. code-block:: text 6391 6392 wpdRes: (kind: branchFunnel) 6393 wpdRes: (kind: singleImpl, singleImplName: "_ZN1A1nEi") 6394 wpdRes: (kind: indir) 6395 6396Additionally, each wpdRes has an optional ``resByArg`` field, which 6397describes the resolutions for calls with all constant integer arguments: 6398 6399.. code-block:: text 6400 6401 resByArg: (ResByArg[, ResByArg]*) 6402 6403where ResByArg is: 6404 6405.. code-block:: text 6406 6407 args: (Arg[, Arg]*), byArg: (kind: UniformRetVal[, info: 0][, byte: 0][, bit: 0]) 6408 6409Where the ``kind`` can be ``Indir``, ``UniformRetVal``, ``UniqueRetVal`` 6410or ``VirtualConstProp``. The ``info`` field is only used if the kind 6411is ``UniformRetVal`` (indicates the uniform return value), or 6412``UniqueRetVal`` (holds the return value associated with the unique vtable 6413(0 or 1)). The ``byte`` and ``bit`` fields are only used if the target does 6414not support the use of absolute symbols to store constants. 6415 6416.. _intrinsicglobalvariables: 6417 6418Intrinsic Global Variables 6419========================== 6420 6421LLVM has a number of "magic" global variables that contain data that 6422affect code generation or other IR semantics. These are documented here. 6423All globals of this sort should have a section specified as 6424"``llvm.metadata``". This section and all globals that start with 6425"``llvm.``" are reserved for use by LLVM. 6426 6427.. _gv_llvmused: 6428 6429The '``llvm.used``' Global Variable 6430----------------------------------- 6431 6432The ``@llvm.used`` global is an array which has 6433:ref:`appending linkage <linkage_appending>`. This array contains a list of 6434pointers to named global variables, functions and aliases which may optionally 6435have a pointer cast formed of bitcast or getelementptr. For example, a legal 6436use of it is: 6437 6438.. code-block:: llvm 6439 6440 @X = global i8 4 6441 @Y = global i32 123 6442 6443 @llvm.used = appending global [2 x i8*] [ 6444 i8* @X, 6445 i8* bitcast (i32* @Y to i8*) 6446 ], section "llvm.metadata" 6447 6448If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler, 6449and linker are required to treat the symbol as if there is a reference to the 6450symbol that it cannot see (which is why they have to be named). For example, if 6451a variable has internal linkage and no references other than that from the 6452``@llvm.used`` list, it cannot be deleted. This is commonly used to represent 6453references from inline asms and other things the compiler cannot "see", and 6454corresponds to "``attribute((used))``" in GNU C. 6455 6456On some targets, the code generator must emit a directive to the 6457assembler or object file to prevent the assembler and linker from 6458molesting the symbol. 6459 6460.. _gv_llvmcompilerused: 6461 6462The '``llvm.compiler.used``' Global Variable 6463-------------------------------------------- 6464 6465The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used`` 6466directive, except that it only prevents the compiler from touching the 6467symbol. On targets that support it, this allows an intelligent linker to 6468optimize references to the symbol without being impeded as it would be 6469by ``@llvm.used``. 6470 6471This is a rare construct that should only be used in rare circumstances, 6472and should not be exposed to source languages. 6473 6474.. _gv_llvmglobalctors: 6475 6476The '``llvm.global_ctors``' Global Variable 6477------------------------------------------- 6478 6479.. code-block:: llvm 6480 6481 %0 = type { i32, void ()*, i8* } 6482 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor, i8* @data }] 6483 6484The ``@llvm.global_ctors`` array contains a list of constructor 6485functions, priorities, and an optional associated global or function. 6486The functions referenced by this array will be called in ascending order 6487of priority (i.e. lowest first) when the module is loaded. The order of 6488functions with the same priority is not defined. 6489 6490If the third field is present, non-null, and points to a global variable 6491or function, the initializer function will only run if the associated 6492data from the current module is not discarded. 6493 6494.. _llvmglobaldtors: 6495 6496The '``llvm.global_dtors``' Global Variable 6497------------------------------------------- 6498 6499.. code-block:: llvm 6500 6501 %0 = type { i32, void ()*, i8* } 6502 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor, i8* @data }] 6503 6504The ``@llvm.global_dtors`` array contains a list of destructor 6505functions, priorities, and an optional associated global or function. 6506The functions referenced by this array will be called in descending 6507order of priority (i.e. highest first) when the module is unloaded. The 6508order of functions with the same priority is not defined. 6509 6510If the third field is present, non-null, and points to a global variable 6511or function, the destructor function will only run if the associated 6512data from the current module is not discarded. 6513 6514Instruction Reference 6515===================== 6516 6517The LLVM instruction set consists of several different classifications 6518of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary 6519instructions <binaryops>`, :ref:`bitwise binary 6520instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and 6521:ref:`other instructions <otherops>`. 6522 6523.. _terminators: 6524 6525Terminator Instructions 6526----------------------- 6527 6528As mentioned :ref:`previously <functionstructure>`, every basic block in a 6529program ends with a "Terminator" instruction, which indicates which 6530block should be executed after the current block is finished. These 6531terminator instructions typically yield a '``void``' value: they produce 6532control flow, not values (the one exception being the 6533':ref:`invoke <i_invoke>`' instruction). 6534 6535The terminator instructions are: ':ref:`ret <i_ret>`', 6536':ref:`br <i_br>`', ':ref:`switch <i_switch>`', 6537':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`', 6538':ref:`callbr <i_callbr>`' 6539':ref:`resume <i_resume>`', ':ref:`catchswitch <i_catchswitch>`', 6540':ref:`catchret <i_catchret>`', 6541':ref:`cleanupret <i_cleanupret>`', 6542and ':ref:`unreachable <i_unreachable>`'. 6543 6544.. _i_ret: 6545 6546'``ret``' Instruction 6547^^^^^^^^^^^^^^^^^^^^^ 6548 6549Syntax: 6550""""""" 6551 6552:: 6553 6554 ret <type> <value> ; Return a value from a non-void function 6555 ret void ; Return from void function 6556 6557Overview: 6558""""""""" 6559 6560The '``ret``' instruction is used to return control flow (and optionally 6561a value) from a function back to the caller. 6562 6563There are two forms of the '``ret``' instruction: one that returns a 6564value and then causes control flow, and one that just causes control 6565flow to occur. 6566 6567Arguments: 6568"""""""""" 6569 6570The '``ret``' instruction optionally accepts a single argument, the 6571return value. The type of the return value must be a ':ref:`first 6572class <t_firstclass>`' type. 6573 6574A function is not :ref:`well formed <wellformed>` if it has a non-void 6575return type and contains a '``ret``' instruction with no return value or 6576a return value with a type that does not match its type, or if it has a 6577void return type and contains a '``ret``' instruction with a return 6578value. 6579 6580Semantics: 6581"""""""""" 6582 6583When the '``ret``' instruction is executed, control flow returns back to 6584the calling function's context. If the caller is a 6585":ref:`call <i_call>`" instruction, execution continues at the 6586instruction after the call. If the caller was an 6587":ref:`invoke <i_invoke>`" instruction, execution continues at the 6588beginning of the "normal" destination block. If the instruction returns 6589a value, that value shall set the call or invoke instruction's return 6590value. 6591 6592Example: 6593"""""""" 6594 6595.. code-block:: llvm 6596 6597 ret i32 5 ; Return an integer value of 5 6598 ret void ; Return from a void function 6599 ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2 6600 6601.. _i_br: 6602 6603'``br``' Instruction 6604^^^^^^^^^^^^^^^^^^^^ 6605 6606Syntax: 6607""""""" 6608 6609:: 6610 6611 br i1 <cond>, label <iftrue>, label <iffalse> 6612 br label <dest> ; Unconditional branch 6613 6614Overview: 6615""""""""" 6616 6617The '``br``' instruction is used to cause control flow to transfer to a 6618different basic block in the current function. There are two forms of 6619this instruction, corresponding to a conditional branch and an 6620unconditional branch. 6621 6622Arguments: 6623"""""""""" 6624 6625The conditional branch form of the '``br``' instruction takes a single 6626'``i1``' value and two '``label``' values. The unconditional form of the 6627'``br``' instruction takes a single '``label``' value as a target. 6628 6629Semantics: 6630"""""""""" 6631 6632Upon execution of a conditional '``br``' instruction, the '``i1``' 6633argument is evaluated. If the value is ``true``, control flows to the 6634'``iftrue``' ``label`` argument. If "cond" is ``false``, control flows 6635to the '``iffalse``' ``label`` argument. 6636 6637Example: 6638"""""""" 6639 6640.. code-block:: llvm 6641 6642 Test: 6643 %cond = icmp eq i32 %a, %b 6644 br i1 %cond, label %IfEqual, label %IfUnequal 6645 IfEqual: 6646 ret i32 1 6647 IfUnequal: 6648 ret i32 0 6649 6650.. _i_switch: 6651 6652'``switch``' Instruction 6653^^^^^^^^^^^^^^^^^^^^^^^^ 6654 6655Syntax: 6656""""""" 6657 6658:: 6659 6660 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ] 6661 6662Overview: 6663""""""""" 6664 6665The '``switch``' instruction is used to transfer control flow to one of 6666several different places. It is a generalization of the '``br``' 6667instruction, allowing a branch to occur to one of many possible 6668destinations. 6669 6670Arguments: 6671"""""""""" 6672 6673The '``switch``' instruction uses three parameters: an integer 6674comparison value '``value``', a default '``label``' destination, and an 6675array of pairs of comparison value constants and '``label``'s. The table 6676is not allowed to contain duplicate constant entries. 6677 6678Semantics: 6679"""""""""" 6680 6681The ``switch`` instruction specifies a table of values and destinations. 6682When the '``switch``' instruction is executed, this table is searched 6683for the given value. If the value is found, control flow is transferred 6684to the corresponding destination; otherwise, control flow is transferred 6685to the default destination. 6686 6687Implementation: 6688""""""""""""""" 6689 6690Depending on properties of the target machine and the particular 6691``switch`` instruction, this instruction may be code generated in 6692different ways. For example, it could be generated as a series of 6693chained conditional branches or with a lookup table. 6694 6695Example: 6696"""""""" 6697 6698.. code-block:: llvm 6699 6700 ; Emulate a conditional br instruction 6701 %Val = zext i1 %value to i32 6702 switch i32 %Val, label %truedest [ i32 0, label %falsedest ] 6703 6704 ; Emulate an unconditional br instruction 6705 switch i32 0, label %dest [ ] 6706 6707 ; Implement a jump table: 6708 switch i32 %val, label %otherwise [ i32 0, label %onzero 6709 i32 1, label %onone 6710 i32 2, label %ontwo ] 6711 6712.. _i_indirectbr: 6713 6714'``indirectbr``' Instruction 6715^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6716 6717Syntax: 6718""""""" 6719 6720:: 6721 6722 indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ] 6723 6724Overview: 6725""""""""" 6726 6727The '``indirectbr``' instruction implements an indirect branch to a 6728label within the current function, whose address is specified by 6729"``address``". Address must be derived from a 6730:ref:`blockaddress <blockaddress>` constant. 6731 6732Arguments: 6733"""""""""" 6734 6735The '``address``' argument is the address of the label to jump to. The 6736rest of the arguments indicate the full set of possible destinations 6737that the address may point to. Blocks are allowed to occur multiple 6738times in the destination list, though this isn't particularly useful. 6739 6740This destination list is required so that dataflow analysis has an 6741accurate understanding of the CFG. 6742 6743Semantics: 6744"""""""""" 6745 6746Control transfers to the block specified in the address argument. All 6747possible destination blocks must be listed in the label list, otherwise 6748this instruction has undefined behavior. This implies that jumps to 6749labels defined in other functions have undefined behavior as well. 6750 6751Implementation: 6752""""""""""""""" 6753 6754This is typically implemented with a jump through a register. 6755 6756Example: 6757"""""""" 6758 6759.. code-block:: llvm 6760 6761 indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ] 6762 6763.. _i_invoke: 6764 6765'``invoke``' Instruction 6766^^^^^^^^^^^^^^^^^^^^^^^^ 6767 6768Syntax: 6769""""""" 6770 6771:: 6772 6773 <result> = invoke [cconv] [ret attrs] [addrspace(<num>)] [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs] 6774 [operand bundles] to label <normal label> unwind label <exception label> 6775 6776Overview: 6777""""""""" 6778 6779The '``invoke``' instruction causes control to transfer to a specified 6780function, with the possibility of control flow transfer to either the 6781'``normal``' label or the '``exception``' label. If the callee function 6782returns with the "``ret``" instruction, control flow will return to the 6783"normal" label. If the callee (or any indirect callees) returns via the 6784":ref:`resume <i_resume>`" instruction or other exception handling 6785mechanism, control is interrupted and continued at the dynamically 6786nearest "exception" label. 6787 6788The '``exception``' label is a `landing 6789pad <ExceptionHandling.html#overview>`_ for the exception. As such, 6790'``exception``' label is required to have the 6791":ref:`landingpad <i_landingpad>`" instruction, which contains the 6792information about the behavior of the program after unwinding happens, 6793as its first non-PHI instruction. The restrictions on the 6794"``landingpad``" instruction's tightly couples it to the "``invoke``" 6795instruction, so that the important information contained within the 6796"``landingpad``" instruction can't be lost through normal code motion. 6797 6798Arguments: 6799"""""""""" 6800 6801This instruction requires several arguments: 6802 6803#. The optional "cconv" marker indicates which :ref:`calling 6804 convention <callingconv>` the call should use. If none is 6805 specified, the call defaults to using C calling conventions. 6806#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 6807 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 6808 are valid here. 6809#. The optional addrspace attribute can be used to indicate the address space 6810 of the called function. If it is not specified, the program address space 6811 from the :ref:`datalayout string<langref_datalayout>` will be used. 6812#. '``ty``': the type of the call instruction itself which is also the 6813 type of the return value. Functions that return no value are marked 6814 ``void``. 6815#. '``fnty``': shall be the signature of the function being invoked. The 6816 argument types must match the types implied by this signature. This 6817 type can be omitted if the function is not varargs. 6818#. '``fnptrval``': An LLVM value containing a pointer to a function to 6819 be invoked. In most cases, this is a direct function invocation, but 6820 indirect ``invoke``'s are just as possible, calling an arbitrary pointer 6821 to function value. 6822#. '``function args``': argument list whose types match the function 6823 signature argument types and parameter attributes. All arguments must 6824 be of :ref:`first class <t_firstclass>` type. If the function signature 6825 indicates the function accepts a variable number of arguments, the 6826 extra arguments can be specified. 6827#. '``normal label``': the label reached when the called function 6828 executes a '``ret``' instruction. 6829#. '``exception label``': the label reached when a callee returns via 6830 the :ref:`resume <i_resume>` instruction or other exception handling 6831 mechanism. 6832#. The optional :ref:`function attributes <fnattrs>` list. 6833#. The optional :ref:`operand bundles <opbundles>` list. 6834 6835Semantics: 6836"""""""""" 6837 6838This instruction is designed to operate as a standard '``call``' 6839instruction in most regards. The primary difference is that it 6840establishes an association with a label, which is used by the runtime 6841library to unwind the stack. 6842 6843This instruction is used in languages with destructors to ensure that 6844proper cleanup is performed in the case of either a ``longjmp`` or a 6845thrown exception. Additionally, this is important for implementation of 6846'``catch``' clauses in high-level languages that support them. 6847 6848For the purposes of the SSA form, the definition of the value returned 6849by the '``invoke``' instruction is deemed to occur on the edge from the 6850current block to the "normal" label. If the callee unwinds then no 6851return value is available. 6852 6853Example: 6854"""""""" 6855 6856.. code-block:: llvm 6857 6858 %retval = invoke i32 @Test(i32 15) to label %Continue 6859 unwind label %TestCleanup ; i32:retval set 6860 %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue 6861 unwind label %TestCleanup ; i32:retval set 6862 6863.. _i_callbr: 6864 6865'``callbr``' Instruction 6866^^^^^^^^^^^^^^^^^^^^^^^^ 6867 6868Syntax: 6869""""""" 6870 6871:: 6872 6873 <result> = callbr [cconv] [ret attrs] [addrspace(<num>)] [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs] 6874 [operand bundles] to label <normal label> or jump [other labels] 6875 6876Overview: 6877""""""""" 6878 6879The '``callbr``' instruction causes control to transfer to a specified 6880function, with the possibility of control flow transfer to either the 6881'``normal``' label or one of the '``other``' labels. 6882 6883This instruction should only be used to implement the "goto" feature of gcc 6884style inline assembly. Any other usage is an error in the IR verifier. 6885 6886Arguments: 6887"""""""""" 6888 6889This instruction requires several arguments: 6890 6891#. The optional "cconv" marker indicates which :ref:`calling 6892 convention <callingconv>` the call should use. If none is 6893 specified, the call defaults to using C calling conventions. 6894#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 6895 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 6896 are valid here. 6897#. The optional addrspace attribute can be used to indicate the address space 6898 of the called function. If it is not specified, the program address space 6899 from the :ref:`datalayout string<langref_datalayout>` will be used. 6900#. '``ty``': the type of the call instruction itself which is also the 6901 type of the return value. Functions that return no value are marked 6902 ``void``. 6903#. '``fnty``': shall be the signature of the function being called. The 6904 argument types must match the types implied by this signature. This 6905 type can be omitted if the function is not varargs. 6906#. '``fnptrval``': An LLVM value containing a pointer to a function to 6907 be called. In most cases, this is a direct function call, but 6908 indirect ``callbr``'s are just as possible, calling an arbitrary pointer 6909 to function value. 6910#. '``function args``': argument list whose types match the function 6911 signature argument types and parameter attributes. All arguments must 6912 be of :ref:`first class <t_firstclass>` type. If the function signature 6913 indicates the function accepts a variable number of arguments, the 6914 extra arguments can be specified. 6915#. '``normal label``': the label reached when the called function 6916 executes a '``ret``' instruction. 6917#. '``other labels``': the labels reached when a callee transfers control 6918 to a location other than the normal '``normal label``' 6919#. The optional :ref:`function attributes <fnattrs>` list. 6920#. The optional :ref:`operand bundles <opbundles>` list. 6921 6922Semantics: 6923"""""""""" 6924 6925This instruction is designed to operate as a standard '``call``' 6926instruction in most regards. The primary difference is that it 6927establishes an association with additional labels to define where control 6928flow goes after the call. 6929 6930The only use of this today is to implement the "goto" feature of gcc inline 6931assembly where additional labels can be provided as locations for the inline 6932assembly to jump to. 6933 6934Example: 6935"""""""" 6936 6937.. code-block:: text 6938 6939 callbr void asm "", "r,x"(i32 %x, i8 *blockaddress(@foo, %fail)) 6940 to label %normal or jump [label %fail] 6941 6942.. _i_resume: 6943 6944'``resume``' Instruction 6945^^^^^^^^^^^^^^^^^^^^^^^^ 6946 6947Syntax: 6948""""""" 6949 6950:: 6951 6952 resume <type> <value> 6953 6954Overview: 6955""""""""" 6956 6957The '``resume``' instruction is a terminator instruction that has no 6958successors. 6959 6960Arguments: 6961"""""""""" 6962 6963The '``resume``' instruction requires one argument, which must have the 6964same type as the result of any '``landingpad``' instruction in the same 6965function. 6966 6967Semantics: 6968"""""""""" 6969 6970The '``resume``' instruction resumes propagation of an existing 6971(in-flight) exception whose unwinding was interrupted with a 6972:ref:`landingpad <i_landingpad>` instruction. 6973 6974Example: 6975"""""""" 6976 6977.. code-block:: llvm 6978 6979 resume { i8*, i32 } %exn 6980 6981.. _i_catchswitch: 6982 6983'``catchswitch``' Instruction 6984^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6985 6986Syntax: 6987""""""" 6988 6989:: 6990 6991 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller 6992 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default> 6993 6994Overview: 6995""""""""" 6996 6997The '``catchswitch``' instruction is used by `LLVM's exception handling system 6998<ExceptionHandling.html#overview>`_ to describe the set of possible catch handlers 6999that may be executed by the :ref:`EH personality routine <personalityfn>`. 7000 7001Arguments: 7002"""""""""" 7003 7004The ``parent`` argument is the token of the funclet that contains the 7005``catchswitch`` instruction. If the ``catchswitch`` is not inside a funclet, 7006this operand may be the token ``none``. 7007 7008The ``default`` argument is the label of another basic block beginning with 7009either a ``cleanuppad`` or ``catchswitch`` instruction. This unwind destination 7010must be a legal target with respect to the ``parent`` links, as described in 7011the `exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_. 7012 7013The ``handlers`` are a nonempty list of successor blocks that each begin with a 7014:ref:`catchpad <i_catchpad>` instruction. 7015 7016Semantics: 7017"""""""""" 7018 7019Executing this instruction transfers control to one of the successors in 7020``handlers``, if appropriate, or continues to unwind via the unwind label if 7021present. 7022 7023The ``catchswitch`` is both a terminator and a "pad" instruction, meaning that 7024it must be both the first non-phi instruction and last instruction in the basic 7025block. Therefore, it must be the only non-phi instruction in the block. 7026 7027Example: 7028"""""""" 7029 7030.. code-block:: text 7031 7032 dispatch1: 7033 %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to caller 7034 dispatch2: 7035 %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup 7036 7037.. _i_catchret: 7038 7039'``catchret``' Instruction 7040^^^^^^^^^^^^^^^^^^^^^^^^^^ 7041 7042Syntax: 7043""""""" 7044 7045:: 7046 7047 catchret from <token> to label <normal> 7048 7049Overview: 7050""""""""" 7051 7052The '``catchret``' instruction is a terminator instruction that has a 7053single successor. 7054 7055 7056Arguments: 7057"""""""""" 7058 7059The first argument to a '``catchret``' indicates which ``catchpad`` it 7060exits. It must be a :ref:`catchpad <i_catchpad>`. 7061The second argument to a '``catchret``' specifies where control will 7062transfer to next. 7063 7064Semantics: 7065"""""""""" 7066 7067The '``catchret``' instruction ends an existing (in-flight) exception whose 7068unwinding was interrupted with a :ref:`catchpad <i_catchpad>` instruction. The 7069:ref:`personality function <personalityfn>` gets a chance to execute arbitrary 7070code to, for example, destroy the active exception. Control then transfers to 7071``normal``. 7072 7073The ``token`` argument must be a token produced by a ``catchpad`` instruction. 7074If the specified ``catchpad`` is not the most-recently-entered not-yet-exited 7075funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 7076the ``catchret``'s behavior is undefined. 7077 7078Example: 7079"""""""" 7080 7081.. code-block:: text 7082 7083 catchret from %catch label %continue 7084 7085.. _i_cleanupret: 7086 7087'``cleanupret``' Instruction 7088^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 7089 7090Syntax: 7091""""""" 7092 7093:: 7094 7095 cleanupret from <value> unwind label <continue> 7096 cleanupret from <value> unwind to caller 7097 7098Overview: 7099""""""""" 7100 7101The '``cleanupret``' instruction is a terminator instruction that has 7102an optional successor. 7103 7104 7105Arguments: 7106"""""""""" 7107 7108The '``cleanupret``' instruction requires one argument, which indicates 7109which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_cleanuppad>`. 7110If the specified ``cleanuppad`` is not the most-recently-entered not-yet-exited 7111funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 7112the ``cleanupret``'s behavior is undefined. 7113 7114The '``cleanupret``' instruction also has an optional successor, ``continue``, 7115which must be the label of another basic block beginning with either a 7116``cleanuppad`` or ``catchswitch`` instruction. This unwind destination must 7117be a legal target with respect to the ``parent`` links, as described in the 7118`exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_. 7119 7120Semantics: 7121"""""""""" 7122 7123The '``cleanupret``' instruction indicates to the 7124:ref:`personality function <personalityfn>` that one 7125:ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended. 7126It transfers control to ``continue`` or unwinds out of the function. 7127 7128Example: 7129"""""""" 7130 7131.. code-block:: text 7132 7133 cleanupret from %cleanup unwind to caller 7134 cleanupret from %cleanup unwind label %continue 7135 7136.. _i_unreachable: 7137 7138'``unreachable``' Instruction 7139^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 7140 7141Syntax: 7142""""""" 7143 7144:: 7145 7146 unreachable 7147 7148Overview: 7149""""""""" 7150 7151The '``unreachable``' instruction has no defined semantics. This 7152instruction is used to inform the optimizer that a particular portion of 7153the code is not reachable. This can be used to indicate that the code 7154after a no-return function cannot be reached, and other facts. 7155 7156Semantics: 7157"""""""""" 7158 7159The '``unreachable``' instruction has no defined semantics. 7160 7161.. _unaryops: 7162 7163Unary Operations 7164----------------- 7165 7166Unary operators require a single operand, execute an operation on 7167it, and produce a single value. The operand might represent multiple 7168data, as is the case with the :ref:`vector <t_vector>` data type. The 7169result value has the same type as its operand. 7170 7171.. _i_fneg: 7172 7173'``fneg``' Instruction 7174^^^^^^^^^^^^^^^^^^^^^^ 7175 7176Syntax: 7177""""""" 7178 7179:: 7180 7181 <result> = fneg [fast-math flags]* <ty> <op1> ; yields ty:result 7182 7183Overview: 7184""""""""" 7185 7186The '``fneg``' instruction returns the negation of its operand. 7187 7188Arguments: 7189"""""""""" 7190 7191The argument to the '``fneg``' instruction must be a 7192:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 7193floating-point values. 7194 7195Semantics: 7196"""""""""" 7197 7198The value produced is a copy of the operand with its sign bit flipped. 7199This instruction can also take any number of :ref:`fast-math 7200flags <fastmath>`, which are optimization hints to enable otherwise 7201unsafe floating-point optimizations: 7202 7203Example: 7204"""""""" 7205 7206.. code-block:: text 7207 7208 <result> = fneg float %val ; yields float:result = -%var 7209 7210.. _binaryops: 7211 7212Binary Operations 7213----------------- 7214 7215Binary operators are used to do most of the computation in a program. 7216They require two operands of the same type, execute an operation on 7217them, and produce a single value. The operands might represent multiple 7218data, as is the case with the :ref:`vector <t_vector>` data type. The 7219result value has the same type as its operands. 7220 7221There are several different binary operators: 7222 7223.. _i_add: 7224 7225'``add``' Instruction 7226^^^^^^^^^^^^^^^^^^^^^ 7227 7228Syntax: 7229""""""" 7230 7231:: 7232 7233 <result> = add <ty> <op1>, <op2> ; yields ty:result 7234 <result> = add nuw <ty> <op1>, <op2> ; yields ty:result 7235 <result> = add nsw <ty> <op1>, <op2> ; yields ty:result 7236 <result> = add nuw nsw <ty> <op1>, <op2> ; yields ty:result 7237 7238Overview: 7239""""""""" 7240 7241The '``add``' instruction returns the sum of its two operands. 7242 7243Arguments: 7244"""""""""" 7245 7246The two arguments to the '``add``' instruction must be 7247:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7248arguments must have identical types. 7249 7250Semantics: 7251"""""""""" 7252 7253The value produced is the integer sum of the two operands. 7254 7255If the sum has unsigned overflow, the result returned is the 7256mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of 7257the result. 7258 7259Because LLVM integers use a two's complement representation, this 7260instruction is appropriate for both signed and unsigned integers. 7261 7262``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 7263respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 7264result value of the ``add`` is a :ref:`poison value <poisonvalues>` if 7265unsigned and/or signed overflow, respectively, occurs. 7266 7267Example: 7268"""""""" 7269 7270.. code-block:: text 7271 7272 <result> = add i32 4, %var ; yields i32:result = 4 + %var 7273 7274.. _i_fadd: 7275 7276'``fadd``' Instruction 7277^^^^^^^^^^^^^^^^^^^^^^ 7278 7279Syntax: 7280""""""" 7281 7282:: 7283 7284 <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 7285 7286Overview: 7287""""""""" 7288 7289The '``fadd``' instruction returns the sum of its two operands. 7290 7291Arguments: 7292"""""""""" 7293 7294The two arguments to the '``fadd``' instruction must be 7295:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 7296floating-point values. Both arguments must have identical types. 7297 7298Semantics: 7299"""""""""" 7300 7301The value produced is the floating-point sum of the two operands. 7302This instruction is assumed to execute in the default :ref:`floating-point 7303environment <floatenv>`. 7304This instruction can also take any number of :ref:`fast-math 7305flags <fastmath>`, which are optimization hints to enable otherwise 7306unsafe floating-point optimizations: 7307 7308Example: 7309"""""""" 7310 7311.. code-block:: text 7312 7313 <result> = fadd float 4.0, %var ; yields float:result = 4.0 + %var 7314 7315'``sub``' Instruction 7316^^^^^^^^^^^^^^^^^^^^^ 7317 7318Syntax: 7319""""""" 7320 7321:: 7322 7323 <result> = sub <ty> <op1>, <op2> ; yields ty:result 7324 <result> = sub nuw <ty> <op1>, <op2> ; yields ty:result 7325 <result> = sub nsw <ty> <op1>, <op2> ; yields ty:result 7326 <result> = sub nuw nsw <ty> <op1>, <op2> ; yields ty:result 7327 7328Overview: 7329""""""""" 7330 7331The '``sub``' instruction returns the difference of its two operands. 7332 7333Note that the '``sub``' instruction is used to represent the '``neg``' 7334instruction present in most other intermediate representations. 7335 7336Arguments: 7337"""""""""" 7338 7339The two arguments to the '``sub``' instruction must be 7340:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7341arguments must have identical types. 7342 7343Semantics: 7344"""""""""" 7345 7346The value produced is the integer difference of the two operands. 7347 7348If the difference has unsigned overflow, the result returned is the 7349mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of 7350the result. 7351 7352Because LLVM integers use a two's complement representation, this 7353instruction is appropriate for both signed and unsigned integers. 7354 7355``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 7356respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 7357result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if 7358unsigned and/or signed overflow, respectively, occurs. 7359 7360Example: 7361"""""""" 7362 7363.. code-block:: text 7364 7365 <result> = sub i32 4, %var ; yields i32:result = 4 - %var 7366 <result> = sub i32 0, %val ; yields i32:result = -%var 7367 7368.. _i_fsub: 7369 7370'``fsub``' Instruction 7371^^^^^^^^^^^^^^^^^^^^^^ 7372 7373Syntax: 7374""""""" 7375 7376:: 7377 7378 <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 7379 7380Overview: 7381""""""""" 7382 7383The '``fsub``' instruction returns the difference of its two operands. 7384 7385Arguments: 7386"""""""""" 7387 7388The two arguments to the '``fsub``' instruction must be 7389:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 7390floating-point values. Both arguments must have identical types. 7391 7392Semantics: 7393"""""""""" 7394 7395The value produced is the floating-point difference of the two operands. 7396This instruction is assumed to execute in the default :ref:`floating-point 7397environment <floatenv>`. 7398This instruction can also take any number of :ref:`fast-math 7399flags <fastmath>`, which are optimization hints to enable otherwise 7400unsafe floating-point optimizations: 7401 7402Example: 7403"""""""" 7404 7405.. code-block:: text 7406 7407 <result> = fsub float 4.0, %var ; yields float:result = 4.0 - %var 7408 <result> = fsub float -0.0, %val ; yields float:result = -%var 7409 7410'``mul``' Instruction 7411^^^^^^^^^^^^^^^^^^^^^ 7412 7413Syntax: 7414""""""" 7415 7416:: 7417 7418 <result> = mul <ty> <op1>, <op2> ; yields ty:result 7419 <result> = mul nuw <ty> <op1>, <op2> ; yields ty:result 7420 <result> = mul nsw <ty> <op1>, <op2> ; yields ty:result 7421 <result> = mul nuw nsw <ty> <op1>, <op2> ; yields ty:result 7422 7423Overview: 7424""""""""" 7425 7426The '``mul``' instruction returns the product of its two operands. 7427 7428Arguments: 7429"""""""""" 7430 7431The two arguments to the '``mul``' instruction must be 7432:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7433arguments must have identical types. 7434 7435Semantics: 7436"""""""""" 7437 7438The value produced is the integer product of the two operands. 7439 7440If the result of the multiplication has unsigned overflow, the result 7441returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the 7442bit width of the result. 7443 7444Because LLVM integers use a two's complement representation, and the 7445result is the same width as the operands, this instruction returns the 7446correct result for both signed and unsigned integers. If a full product 7447(e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be 7448sign-extended or zero-extended as appropriate to the width of the full 7449product. 7450 7451``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 7452respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 7453result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if 7454unsigned and/or signed overflow, respectively, occurs. 7455 7456Example: 7457"""""""" 7458 7459.. code-block:: text 7460 7461 <result> = mul i32 4, %var ; yields i32:result = 4 * %var 7462 7463.. _i_fmul: 7464 7465'``fmul``' Instruction 7466^^^^^^^^^^^^^^^^^^^^^^ 7467 7468Syntax: 7469""""""" 7470 7471:: 7472 7473 <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 7474 7475Overview: 7476""""""""" 7477 7478The '``fmul``' instruction returns the product of its two operands. 7479 7480Arguments: 7481"""""""""" 7482 7483The two arguments to the '``fmul``' instruction must be 7484:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 7485floating-point values. Both arguments must have identical types. 7486 7487Semantics: 7488"""""""""" 7489 7490The value produced is the floating-point product of the two operands. 7491This instruction is assumed to execute in the default :ref:`floating-point 7492environment <floatenv>`. 7493This instruction can also take any number of :ref:`fast-math 7494flags <fastmath>`, which are optimization hints to enable otherwise 7495unsafe floating-point optimizations: 7496 7497Example: 7498"""""""" 7499 7500.. code-block:: text 7501 7502 <result> = fmul float 4.0, %var ; yields float:result = 4.0 * %var 7503 7504'``udiv``' Instruction 7505^^^^^^^^^^^^^^^^^^^^^^ 7506 7507Syntax: 7508""""""" 7509 7510:: 7511 7512 <result> = udiv <ty> <op1>, <op2> ; yields ty:result 7513 <result> = udiv exact <ty> <op1>, <op2> ; yields ty:result 7514 7515Overview: 7516""""""""" 7517 7518The '``udiv``' instruction returns the quotient of its two operands. 7519 7520Arguments: 7521"""""""""" 7522 7523The two arguments to the '``udiv``' instruction must be 7524:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7525arguments must have identical types. 7526 7527Semantics: 7528"""""""""" 7529 7530The value produced is the unsigned integer quotient of the two operands. 7531 7532Note that unsigned integer division and signed integer division are 7533distinct operations; for signed integer division, use '``sdiv``'. 7534 7535Division by zero is undefined behavior. For vectors, if any element 7536of the divisor is zero, the operation has undefined behavior. 7537 7538 7539If the ``exact`` keyword is present, the result value of the ``udiv`` is 7540a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as 7541such, "((a udiv exact b) mul b) == a"). 7542 7543Example: 7544"""""""" 7545 7546.. code-block:: text 7547 7548 <result> = udiv i32 4, %var ; yields i32:result = 4 / %var 7549 7550'``sdiv``' Instruction 7551^^^^^^^^^^^^^^^^^^^^^^ 7552 7553Syntax: 7554""""""" 7555 7556:: 7557 7558 <result> = sdiv <ty> <op1>, <op2> ; yields ty:result 7559 <result> = sdiv exact <ty> <op1>, <op2> ; yields ty:result 7560 7561Overview: 7562""""""""" 7563 7564The '``sdiv``' instruction returns the quotient of its two operands. 7565 7566Arguments: 7567"""""""""" 7568 7569The two arguments to the '``sdiv``' instruction must be 7570:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7571arguments must have identical types. 7572 7573Semantics: 7574"""""""""" 7575 7576The value produced is the signed integer quotient of the two operands 7577rounded towards zero. 7578 7579Note that signed integer division and unsigned integer division are 7580distinct operations; for unsigned integer division, use '``udiv``'. 7581 7582Division by zero is undefined behavior. For vectors, if any element 7583of the divisor is zero, the operation has undefined behavior. 7584Overflow also leads to undefined behavior; this is a rare case, but can 7585occur, for example, by doing a 32-bit division of -2147483648 by -1. 7586 7587If the ``exact`` keyword is present, the result value of the ``sdiv`` is 7588a :ref:`poison value <poisonvalues>` if the result would be rounded. 7589 7590Example: 7591"""""""" 7592 7593.. code-block:: text 7594 7595 <result> = sdiv i32 4, %var ; yields i32:result = 4 / %var 7596 7597.. _i_fdiv: 7598 7599'``fdiv``' Instruction 7600^^^^^^^^^^^^^^^^^^^^^^ 7601 7602Syntax: 7603""""""" 7604 7605:: 7606 7607 <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 7608 7609Overview: 7610""""""""" 7611 7612The '``fdiv``' instruction returns the quotient of its two operands. 7613 7614Arguments: 7615"""""""""" 7616 7617The two arguments to the '``fdiv``' instruction must be 7618:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 7619floating-point values. Both arguments must have identical types. 7620 7621Semantics: 7622"""""""""" 7623 7624The value produced is the floating-point quotient of the two operands. 7625This instruction is assumed to execute in the default :ref:`floating-point 7626environment <floatenv>`. 7627This instruction can also take any number of :ref:`fast-math 7628flags <fastmath>`, which are optimization hints to enable otherwise 7629unsafe floating-point optimizations: 7630 7631Example: 7632"""""""" 7633 7634.. code-block:: text 7635 7636 <result> = fdiv float 4.0, %var ; yields float:result = 4.0 / %var 7637 7638'``urem``' Instruction 7639^^^^^^^^^^^^^^^^^^^^^^ 7640 7641Syntax: 7642""""""" 7643 7644:: 7645 7646 <result> = urem <ty> <op1>, <op2> ; yields ty:result 7647 7648Overview: 7649""""""""" 7650 7651The '``urem``' instruction returns the remainder from the unsigned 7652division of its two arguments. 7653 7654Arguments: 7655"""""""""" 7656 7657The two arguments to the '``urem``' instruction must be 7658:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7659arguments must have identical types. 7660 7661Semantics: 7662"""""""""" 7663 7664This instruction returns the unsigned integer *remainder* of a division. 7665This instruction always performs an unsigned division to get the 7666remainder. 7667 7668Note that unsigned integer remainder and signed integer remainder are 7669distinct operations; for signed integer remainder, use '``srem``'. 7670 7671Taking the remainder of a division by zero is undefined behavior. 7672For vectors, if any element of the divisor is zero, the operation has 7673undefined behavior. 7674 7675Example: 7676"""""""" 7677 7678.. code-block:: text 7679 7680 <result> = urem i32 4, %var ; yields i32:result = 4 % %var 7681 7682'``srem``' Instruction 7683^^^^^^^^^^^^^^^^^^^^^^ 7684 7685Syntax: 7686""""""" 7687 7688:: 7689 7690 <result> = srem <ty> <op1>, <op2> ; yields ty:result 7691 7692Overview: 7693""""""""" 7694 7695The '``srem``' instruction returns the remainder from the signed 7696division of its two operands. This instruction can also take 7697:ref:`vector <t_vector>` versions of the values in which case the elements 7698must be integers. 7699 7700Arguments: 7701"""""""""" 7702 7703The two arguments to the '``srem``' instruction must be 7704:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7705arguments must have identical types. 7706 7707Semantics: 7708"""""""""" 7709 7710This instruction returns the *remainder* of a division (where the result 7711is either zero or has the same sign as the dividend, ``op1``), not the 7712*modulo* operator (where the result is either zero or has the same sign 7713as the divisor, ``op2``) of a value. For more information about the 7714difference, see `The Math 7715Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a 7716table of how this is implemented in various languages, please see 7717`Wikipedia: modulo 7718operation <http://en.wikipedia.org/wiki/Modulo_operation>`_. 7719 7720Note that signed integer remainder and unsigned integer remainder are 7721distinct operations; for unsigned integer remainder, use '``urem``'. 7722 7723Taking the remainder of a division by zero is undefined behavior. 7724For vectors, if any element of the divisor is zero, the operation has 7725undefined behavior. 7726Overflow also leads to undefined behavior; this is a rare case, but can 7727occur, for example, by taking the remainder of a 32-bit division of 7728-2147483648 by -1. (The remainder doesn't actually overflow, but this 7729rule lets srem be implemented using instructions that return both the 7730result of the division and the remainder.) 7731 7732Example: 7733"""""""" 7734 7735.. code-block:: text 7736 7737 <result> = srem i32 4, %var ; yields i32:result = 4 % %var 7738 7739.. _i_frem: 7740 7741'``frem``' Instruction 7742^^^^^^^^^^^^^^^^^^^^^^ 7743 7744Syntax: 7745""""""" 7746 7747:: 7748 7749 <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 7750 7751Overview: 7752""""""""" 7753 7754The '``frem``' instruction returns the remainder from the division of 7755its two operands. 7756 7757Arguments: 7758"""""""""" 7759 7760The two arguments to the '``frem``' instruction must be 7761:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 7762floating-point values. Both arguments must have identical types. 7763 7764Semantics: 7765"""""""""" 7766 7767The value produced is the floating-point remainder of the two operands. 7768This is the same output as a libm '``fmod``' function, but without any 7769possibility of setting ``errno``. The remainder has the same sign as the 7770dividend. 7771This instruction is assumed to execute in the default :ref:`floating-point 7772environment <floatenv>`. 7773This instruction can also take any number of :ref:`fast-math 7774flags <fastmath>`, which are optimization hints to enable otherwise 7775unsafe floating-point optimizations: 7776 7777Example: 7778"""""""" 7779 7780.. code-block:: text 7781 7782 <result> = frem float 4.0, %var ; yields float:result = 4.0 % %var 7783 7784.. _bitwiseops: 7785 7786Bitwise Binary Operations 7787------------------------- 7788 7789Bitwise binary operators are used to do various forms of bit-twiddling 7790in a program. They are generally very efficient instructions and can 7791commonly be strength reduced from other instructions. They require two 7792operands of the same type, execute an operation on them, and produce a 7793single value. The resulting value is the same type as its operands. 7794 7795'``shl``' Instruction 7796^^^^^^^^^^^^^^^^^^^^^ 7797 7798Syntax: 7799""""""" 7800 7801:: 7802 7803 <result> = shl <ty> <op1>, <op2> ; yields ty:result 7804 <result> = shl nuw <ty> <op1>, <op2> ; yields ty:result 7805 <result> = shl nsw <ty> <op1>, <op2> ; yields ty:result 7806 <result> = shl nuw nsw <ty> <op1>, <op2> ; yields ty:result 7807 7808Overview: 7809""""""""" 7810 7811The '``shl``' instruction returns the first operand shifted to the left 7812a specified number of bits. 7813 7814Arguments: 7815"""""""""" 7816 7817Both arguments to the '``shl``' instruction must be the same 7818:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 7819'``op2``' is treated as an unsigned value. 7820 7821Semantics: 7822"""""""""" 7823 7824The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`, 7825where ``n`` is the width of the result. If ``op2`` is (statically or 7826dynamically) equal to or larger than the number of bits in 7827``op1``, this instruction returns a :ref:`poison value <poisonvalues>`. 7828If the arguments are vectors, each vector element of ``op1`` is shifted 7829by the corresponding shift amount in ``op2``. 7830 7831If the ``nuw`` keyword is present, then the shift produces a poison 7832value if it shifts out any non-zero bits. 7833If the ``nsw`` keyword is present, then the shift produces a poison 7834value if it shifts out any bits that disagree with the resultant sign bit. 7835 7836Example: 7837"""""""" 7838 7839.. code-block:: text 7840 7841 <result> = shl i32 4, %var ; yields i32: 4 << %var 7842 <result> = shl i32 4, 2 ; yields i32: 16 7843 <result> = shl i32 1, 10 ; yields i32: 1024 7844 <result> = shl i32 1, 32 ; undefined 7845 <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4> 7846 7847'``lshr``' Instruction 7848^^^^^^^^^^^^^^^^^^^^^^ 7849 7850Syntax: 7851""""""" 7852 7853:: 7854 7855 <result> = lshr <ty> <op1>, <op2> ; yields ty:result 7856 <result> = lshr exact <ty> <op1>, <op2> ; yields ty:result 7857 7858Overview: 7859""""""""" 7860 7861The '``lshr``' instruction (logical shift right) returns the first 7862operand shifted to the right a specified number of bits with zero fill. 7863 7864Arguments: 7865"""""""""" 7866 7867Both arguments to the '``lshr``' instruction must be the same 7868:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 7869'``op2``' is treated as an unsigned value. 7870 7871Semantics: 7872"""""""""" 7873 7874This instruction always performs a logical shift right operation. The 7875most significant bits of the result will be filled with zero bits after 7876the shift. If ``op2`` is (statically or dynamically) equal to or larger 7877than the number of bits in ``op1``, this instruction returns a :ref:`poison 7878value <poisonvalues>`. If the arguments are vectors, each vector element 7879of ``op1`` is shifted by the corresponding shift amount in ``op2``. 7880 7881If the ``exact`` keyword is present, the result value of the ``lshr`` is 7882a poison value if any of the bits shifted out are non-zero. 7883 7884Example: 7885"""""""" 7886 7887.. code-block:: text 7888 7889 <result> = lshr i32 4, 1 ; yields i32:result = 2 7890 <result> = lshr i32 4, 2 ; yields i32:result = 1 7891 <result> = lshr i8 4, 3 ; yields i8:result = 0 7892 <result> = lshr i8 -2, 1 ; yields i8:result = 0x7F 7893 <result> = lshr i32 1, 32 ; undefined 7894 <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1> 7895 7896'``ashr``' Instruction 7897^^^^^^^^^^^^^^^^^^^^^^ 7898 7899Syntax: 7900""""""" 7901 7902:: 7903 7904 <result> = ashr <ty> <op1>, <op2> ; yields ty:result 7905 <result> = ashr exact <ty> <op1>, <op2> ; yields ty:result 7906 7907Overview: 7908""""""""" 7909 7910The '``ashr``' instruction (arithmetic shift right) returns the first 7911operand shifted to the right a specified number of bits with sign 7912extension. 7913 7914Arguments: 7915"""""""""" 7916 7917Both arguments to the '``ashr``' instruction must be the same 7918:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 7919'``op2``' is treated as an unsigned value. 7920 7921Semantics: 7922"""""""""" 7923 7924This instruction always performs an arithmetic shift right operation, 7925The most significant bits of the result will be filled with the sign bit 7926of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger 7927than the number of bits in ``op1``, this instruction returns a :ref:`poison 7928value <poisonvalues>`. If the arguments are vectors, each vector element 7929of ``op1`` is shifted by the corresponding shift amount in ``op2``. 7930 7931If the ``exact`` keyword is present, the result value of the ``ashr`` is 7932a poison value if any of the bits shifted out are non-zero. 7933 7934Example: 7935"""""""" 7936 7937.. code-block:: text 7938 7939 <result> = ashr i32 4, 1 ; yields i32:result = 2 7940 <result> = ashr i32 4, 2 ; yields i32:result = 1 7941 <result> = ashr i8 4, 3 ; yields i8:result = 0 7942 <result> = ashr i8 -2, 1 ; yields i8:result = -1 7943 <result> = ashr i32 1, 32 ; undefined 7944 <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0> 7945 7946'``and``' Instruction 7947^^^^^^^^^^^^^^^^^^^^^ 7948 7949Syntax: 7950""""""" 7951 7952:: 7953 7954 <result> = and <ty> <op1>, <op2> ; yields ty:result 7955 7956Overview: 7957""""""""" 7958 7959The '``and``' instruction returns the bitwise logical and of its two 7960operands. 7961 7962Arguments: 7963"""""""""" 7964 7965The two arguments to the '``and``' instruction must be 7966:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 7967arguments must have identical types. 7968 7969Semantics: 7970"""""""""" 7971 7972The truth table used for the '``and``' instruction is: 7973 7974+-----+-----+-----+ 7975| In0 | In1 | Out | 7976+-----+-----+-----+ 7977| 0 | 0 | 0 | 7978+-----+-----+-----+ 7979| 0 | 1 | 0 | 7980+-----+-----+-----+ 7981| 1 | 0 | 0 | 7982+-----+-----+-----+ 7983| 1 | 1 | 1 | 7984+-----+-----+-----+ 7985 7986Example: 7987"""""""" 7988 7989.. code-block:: text 7990 7991 <result> = and i32 4, %var ; yields i32:result = 4 & %var 7992 <result> = and i32 15, 40 ; yields i32:result = 8 7993 <result> = and i32 4, 8 ; yields i32:result = 0 7994 7995'``or``' Instruction 7996^^^^^^^^^^^^^^^^^^^^ 7997 7998Syntax: 7999""""""" 8000 8001:: 8002 8003 <result> = or <ty> <op1>, <op2> ; yields ty:result 8004 8005Overview: 8006""""""""" 8007 8008The '``or``' instruction returns the bitwise logical inclusive or of its 8009two operands. 8010 8011Arguments: 8012"""""""""" 8013 8014The two arguments to the '``or``' instruction must be 8015:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8016arguments must have identical types. 8017 8018Semantics: 8019"""""""""" 8020 8021The truth table used for the '``or``' instruction is: 8022 8023+-----+-----+-----+ 8024| In0 | In1 | Out | 8025+-----+-----+-----+ 8026| 0 | 0 | 0 | 8027+-----+-----+-----+ 8028| 0 | 1 | 1 | 8029+-----+-----+-----+ 8030| 1 | 0 | 1 | 8031+-----+-----+-----+ 8032| 1 | 1 | 1 | 8033+-----+-----+-----+ 8034 8035Example: 8036"""""""" 8037 8038:: 8039 8040 <result> = or i32 4, %var ; yields i32:result = 4 | %var 8041 <result> = or i32 15, 40 ; yields i32:result = 47 8042 <result> = or i32 4, 8 ; yields i32:result = 12 8043 8044'``xor``' Instruction 8045^^^^^^^^^^^^^^^^^^^^^ 8046 8047Syntax: 8048""""""" 8049 8050:: 8051 8052 <result> = xor <ty> <op1>, <op2> ; yields ty:result 8053 8054Overview: 8055""""""""" 8056 8057The '``xor``' instruction returns the bitwise logical exclusive or of 8058its two operands. The ``xor`` is used to implement the "one's 8059complement" operation, which is the "~" operator in C. 8060 8061Arguments: 8062"""""""""" 8063 8064The two arguments to the '``xor``' instruction must be 8065:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8066arguments must have identical types. 8067 8068Semantics: 8069"""""""""" 8070 8071The truth table used for the '``xor``' instruction is: 8072 8073+-----+-----+-----+ 8074| In0 | In1 | Out | 8075+-----+-----+-----+ 8076| 0 | 0 | 0 | 8077+-----+-----+-----+ 8078| 0 | 1 | 1 | 8079+-----+-----+-----+ 8080| 1 | 0 | 1 | 8081+-----+-----+-----+ 8082| 1 | 1 | 0 | 8083+-----+-----+-----+ 8084 8085Example: 8086"""""""" 8087 8088.. code-block:: text 8089 8090 <result> = xor i32 4, %var ; yields i32:result = 4 ^ %var 8091 <result> = xor i32 15, 40 ; yields i32:result = 39 8092 <result> = xor i32 4, 8 ; yields i32:result = 12 8093 <result> = xor i32 %V, -1 ; yields i32:result = ~%V 8094 8095Vector Operations 8096----------------- 8097 8098LLVM supports several instructions to represent vector operations in a 8099target-independent manner. These instructions cover the element-access 8100and vector-specific operations needed to process vectors effectively. 8101While LLVM does directly support these vector operations, many 8102sophisticated algorithms will want to use target-specific intrinsics to 8103take full advantage of a specific target. 8104 8105.. _i_extractelement: 8106 8107'``extractelement``' Instruction 8108^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8109 8110Syntax: 8111""""""" 8112 8113:: 8114 8115 <result> = extractelement <n x <ty>> <val>, <ty2> <idx> ; yields <ty> 8116 8117Overview: 8118""""""""" 8119 8120The '``extractelement``' instruction extracts a single scalar element 8121from a vector at a specified index. 8122 8123Arguments: 8124"""""""""" 8125 8126The first operand of an '``extractelement``' instruction is a value of 8127:ref:`vector <t_vector>` type. The second operand is an index indicating 8128the position from which to extract the element. The index may be a 8129variable of any integer type. 8130 8131Semantics: 8132"""""""""" 8133 8134The result is a scalar of the same type as the element type of ``val``. 8135Its value is the value at position ``idx`` of ``val``. If ``idx`` 8136exceeds the length of ``val``, the result is a 8137:ref:`poison value <poisonvalues>`. 8138 8139Example: 8140"""""""" 8141 8142.. code-block:: text 8143 8144 <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32 8145 8146.. _i_insertelement: 8147 8148'``insertelement``' Instruction 8149^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8150 8151Syntax: 8152""""""" 8153 8154:: 8155 8156 <result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <n x <ty>> 8157 8158Overview: 8159""""""""" 8160 8161The '``insertelement``' instruction inserts a scalar element into a 8162vector at a specified index. 8163 8164Arguments: 8165"""""""""" 8166 8167The first operand of an '``insertelement``' instruction is a value of 8168:ref:`vector <t_vector>` type. The second operand is a scalar value whose 8169type must equal the element type of the first operand. The third operand 8170is an index indicating the position at which to insert the value. The 8171index may be a variable of any integer type. 8172 8173Semantics: 8174"""""""""" 8175 8176The result is a vector of the same type as ``val``. Its element values 8177are those of ``val`` except at position ``idx``, where it gets the value 8178``elt``. If ``idx`` exceeds the length of ``val``, the result 8179is a :ref:`poison value <poisonvalues>`. 8180 8181Example: 8182"""""""" 8183 8184.. code-block:: text 8185 8186 <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32> 8187 8188.. _i_shufflevector: 8189 8190'``shufflevector``' Instruction 8191^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8192 8193Syntax: 8194""""""" 8195 8196:: 8197 8198 <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>> 8199 8200Overview: 8201""""""""" 8202 8203The '``shufflevector``' instruction constructs a permutation of elements 8204from two input vectors, returning a vector with the same element type as 8205the input and length that is the same as the shuffle mask. 8206 8207Arguments: 8208"""""""""" 8209 8210The first two operands of a '``shufflevector``' instruction are vectors 8211with the same type. The third argument is a shuffle mask whose element 8212type is always 'i32'. The result of the instruction is a vector whose 8213length is the same as the shuffle mask and whose element type is the 8214same as the element type of the first two operands. 8215 8216The shuffle mask operand is required to be a constant vector with either 8217constant integer or undef values. 8218 8219Semantics: 8220"""""""""" 8221 8222The elements of the two input vectors are numbered from left to right 8223across both of the vectors. The shuffle mask operand specifies, for each 8224element of the result vector, which element of the two input vectors the 8225result element gets. If the shuffle mask is undef, the result vector is 8226undef. If any element of the mask operand is undef, that element of the 8227result is undef. If the shuffle mask selects an undef element from one 8228of the input vectors, the resulting element is undef. 8229 8230Example: 8231"""""""" 8232 8233.. code-block:: text 8234 8235 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 8236 <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32> 8237 <result> = shufflevector <4 x i32> %v1, <4 x i32> undef, 8238 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle. 8239 <result> = shufflevector <8 x i32> %v1, <8 x i32> undef, 8240 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> 8241 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 8242 <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32> 8243 8244Aggregate Operations 8245-------------------- 8246 8247LLVM supports several instructions for working with 8248:ref:`aggregate <t_aggregate>` values. 8249 8250.. _i_extractvalue: 8251 8252'``extractvalue``' Instruction 8253^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8254 8255Syntax: 8256""""""" 8257 8258:: 8259 8260 <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}* 8261 8262Overview: 8263""""""""" 8264 8265The '``extractvalue``' instruction extracts the value of a member field 8266from an :ref:`aggregate <t_aggregate>` value. 8267 8268Arguments: 8269"""""""""" 8270 8271The first operand of an '``extractvalue``' instruction is a value of 8272:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The other operands are 8273constant indices to specify which value to extract in a similar manner 8274as indices in a '``getelementptr``' instruction. 8275 8276The major differences to ``getelementptr`` indexing are: 8277 8278- Since the value being indexed is not a pointer, the first index is 8279 omitted and assumed to be zero. 8280- At least one index must be specified. 8281- Not only struct indices but also array indices must be in bounds. 8282 8283Semantics: 8284"""""""""" 8285 8286The result is the value at the position in the aggregate specified by 8287the index operands. 8288 8289Example: 8290"""""""" 8291 8292.. code-block:: text 8293 8294 <result> = extractvalue {i32, float} %agg, 0 ; yields i32 8295 8296.. _i_insertvalue: 8297 8298'``insertvalue``' Instruction 8299^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8300 8301Syntax: 8302""""""" 8303 8304:: 8305 8306 <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type> 8307 8308Overview: 8309""""""""" 8310 8311The '``insertvalue``' instruction inserts a value into a member field in 8312an :ref:`aggregate <t_aggregate>` value. 8313 8314Arguments: 8315"""""""""" 8316 8317The first operand of an '``insertvalue``' instruction is a value of 8318:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The second operand is 8319a first-class value to insert. The following operands are constant 8320indices indicating the position at which to insert the value in a 8321similar manner as indices in a '``extractvalue``' instruction. The value 8322to insert must have the same type as the value identified by the 8323indices. 8324 8325Semantics: 8326"""""""""" 8327 8328The result is an aggregate of the same type as ``val``. Its value is 8329that of ``val`` except that the value at the position specified by the 8330indices is that of ``elt``. 8331 8332Example: 8333"""""""" 8334 8335.. code-block:: llvm 8336 8337 %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef} 8338 %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val} 8339 %agg3 = insertvalue {i32, {float}} undef, float %val, 1, 0 ; yields {i32 undef, {float %val}} 8340 8341.. _memoryops: 8342 8343Memory Access and Addressing Operations 8344--------------------------------------- 8345 8346A key design point of an SSA-based representation is how it represents 8347memory. In LLVM, no memory locations are in SSA form, which makes things 8348very simple. This section describes how to read, write, and allocate 8349memory in LLVM. 8350 8351.. _i_alloca: 8352 8353'``alloca``' Instruction 8354^^^^^^^^^^^^^^^^^^^^^^^^ 8355 8356Syntax: 8357""""""" 8358 8359:: 8360 8361 <result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] [, addrspace(<num>)] ; yields type addrspace(num)*:result 8362 8363Overview: 8364""""""""" 8365 8366The '``alloca``' instruction allocates memory on the stack frame of the 8367currently executing function, to be automatically released when this 8368function returns to its caller. The object is always allocated in the 8369address space for allocas indicated in the datalayout. 8370 8371Arguments: 8372"""""""""" 8373 8374The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements`` 8375bytes of memory on the runtime stack, returning a pointer of the 8376appropriate type to the program. If "NumElements" is specified, it is 8377the number of elements allocated, otherwise "NumElements" is defaulted 8378to be one. If a constant alignment is specified, the value result of the 8379allocation is guaranteed to be aligned to at least that boundary. The 8380alignment may not be greater than ``1 << 29``. If not specified, or if 8381zero, the target can choose to align the allocation on any convenient 8382boundary compatible with the type. 8383 8384'``type``' may be any sized type. 8385 8386Semantics: 8387"""""""""" 8388 8389Memory is allocated; a pointer is returned. The allocated memory is 8390uninitialized, and loading from uninitialized memory produces an undefined 8391value. The operation itself is undefined if there is insufficient stack 8392space for the allocation.'``alloca``'d memory is automatically released 8393when the function returns. The '``alloca``' instruction is commonly used 8394to represent automatic variables that must have an address available. When 8395the function returns (either with the ``ret`` or ``resume`` instructions), 8396the memory is reclaimed. Allocating zero bytes is legal, but the returned 8397pointer may not be unique. The order in which memory is allocated (ie., 8398which way the stack grows) is not specified. 8399 8400Example: 8401"""""""" 8402 8403.. code-block:: llvm 8404 8405 %ptr = alloca i32 ; yields i32*:ptr 8406 %ptr = alloca i32, i32 4 ; yields i32*:ptr 8407 %ptr = alloca i32, i32 4, align 1024 ; yields i32*:ptr 8408 %ptr = alloca i32, align 1024 ; yields i32*:ptr 8409 8410.. _i_load: 8411 8412'``load``' Instruction 8413^^^^^^^^^^^^^^^^^^^^^^ 8414 8415Syntax: 8416""""""" 8417 8418:: 8419 8420 <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !invariant.group !<index>][, !nonnull !<index>][, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !align !<align_node>] 8421 <result> = load atomic [volatile] <ty>, <ty>* <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<index>] 8422 !<index> = !{ i32 1 } 8423 !<deref_bytes_node> = !{i64 <dereferenceable_bytes>} 8424 !<align_node> = !{ i64 <value_alignment> } 8425 8426Overview: 8427""""""""" 8428 8429The '``load``' instruction is used to read from memory. 8430 8431Arguments: 8432"""""""""" 8433 8434The argument to the ``load`` instruction specifies the memory address from which 8435to load. The type specified must be a :ref:`first class <t_firstclass>` type of 8436known size (i.e. not containing an :ref:`opaque structural type <t_opaque>`). If 8437the ``load`` is marked as ``volatile``, then the optimizer is not allowed to 8438modify the number or order of execution of this ``load`` with other 8439:ref:`volatile operations <volatile>`. 8440 8441If the ``load`` is marked as ``atomic``, it takes an extra :ref:`ordering 8442<ordering>` and optional ``syncscope("<target-scope>")`` argument. The 8443``release`` and ``acq_rel`` orderings are not valid on ``load`` instructions. 8444Atomic loads produce :ref:`defined <memmodel>` results when they may see 8445multiple atomic stores. The type of the pointee must be an integer, pointer, or 8446floating-point type whose bit width is a power of two greater than or equal to 8447eight and less than or equal to a target-specific size limit. ``align`` must be 8448explicitly specified on atomic loads, and the load has undefined behavior if the 8449alignment is not set to a value which is at least the size in bytes of the 8450pointee. ``!nontemporal`` does not have any defined semantics for atomic loads. 8451 8452The optional constant ``align`` argument specifies the alignment of the 8453operation (that is, the alignment of the memory address). A value of 0 8454or an omitted ``align`` argument means that the operation has the ABI 8455alignment for the target. It is the responsibility of the code emitter 8456to ensure that the alignment information is correct. Overestimating the 8457alignment results in undefined behavior. Underestimating the alignment 8458may produce less efficient code. An alignment of 1 is always safe. The 8459maximum possible alignment is ``1 << 29``. An alignment value higher 8460than the size of the loaded type implies memory up to the alignment 8461value bytes can be safely loaded without trapping in the default 8462address space. Access of the high bytes can interfere with debugging 8463tools, so should not be accessed if the function has the 8464``sanitize_thread`` or ``sanitize_address`` attributes. 8465 8466The optional ``!nontemporal`` metadata must reference a single 8467metadata name ``<index>`` corresponding to a metadata node with one 8468``i32`` entry of value 1. The existence of the ``!nontemporal`` 8469metadata on the instruction tells the optimizer and code generator 8470that this load is not expected to be reused in the cache. The code 8471generator may select special instructions to save cache bandwidth, such 8472as the ``MOVNT`` instruction on x86. 8473 8474The optional ``!invariant.load`` metadata must reference a single 8475metadata name ``<index>`` corresponding to a metadata node with no 8476entries. If a load instruction tagged with the ``!invariant.load`` 8477metadata is executed, the optimizer may assume the memory location 8478referenced by the load contains the same value at all points in the 8479program where the memory location is known to be dereferenceable; 8480otherwise, the behavior is undefined. 8481 8482The optional ``!invariant.group`` metadata must reference a single metadata name 8483 ``<index>`` corresponding to a metadata node with no entries. 8484 See ``invariant.group`` metadata. 8485 8486The optional ``!nonnull`` metadata must reference a single 8487metadata name ``<index>`` corresponding to a metadata node with no 8488entries. The existence of the ``!nonnull`` metadata on the 8489instruction tells the optimizer that the value loaded is known to 8490never be null. If the value is null at runtime, the behavior is undefined. 8491This is analogous to the ``nonnull`` attribute on parameters and return 8492values. This metadata can only be applied to loads of a pointer type. 8493 8494The optional ``!dereferenceable`` metadata must reference a single metadata 8495name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64`` 8496entry. The existence of the ``!dereferenceable`` metadata on the instruction 8497tells the optimizer that the value loaded is known to be dereferenceable. 8498The number of bytes known to be dereferenceable is specified by the integer 8499value in the metadata node. This is analogous to the ''dereferenceable'' 8500attribute on parameters and return values. This metadata can only be applied 8501to loads of a pointer type. 8502 8503The optional ``!dereferenceable_or_null`` metadata must reference a single 8504metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one 8505``i64`` entry. The existence of the ``!dereferenceable_or_null`` metadata on the 8506instruction tells the optimizer that the value loaded is known to be either 8507dereferenceable or null. 8508The number of bytes known to be dereferenceable is specified by the integer 8509value in the metadata node. This is analogous to the ''dereferenceable_or_null'' 8510attribute on parameters and return values. This metadata can only be applied 8511to loads of a pointer type. 8512 8513The optional ``!align`` metadata must reference a single metadata name 8514``<align_node>`` corresponding to a metadata node with one ``i64`` entry. 8515The existence of the ``!align`` metadata on the instruction tells the 8516optimizer that the value loaded is known to be aligned to a boundary specified 8517by the integer value in the metadata node. The alignment must be a power of 2. 8518This is analogous to the ''align'' attribute on parameters and return values. 8519This metadata can only be applied to loads of a pointer type. If the returned 8520value is not appropriately aligned at runtime, the behavior is undefined. 8521 8522Semantics: 8523"""""""""" 8524 8525The location of memory pointed to is loaded. If the value being loaded 8526is of scalar type then the number of bytes read does not exceed the 8527minimum number of bytes needed to hold all bits of the type. For 8528example, loading an ``i24`` reads at most three bytes. When loading a 8529value of a type like ``i20`` with a size that is not an integral number 8530of bytes, the result is undefined if the value was not originally 8531written using a store of the same type. 8532 8533Examples: 8534""""""""" 8535 8536.. code-block:: llvm 8537 8538 %ptr = alloca i32 ; yields i32*:ptr 8539 store i32 3, i32* %ptr ; yields void 8540 %val = load i32, i32* %ptr ; yields i32:val = i32 3 8541 8542.. _i_store: 8543 8544'``store``' Instruction 8545^^^^^^^^^^^^^^^^^^^^^^^ 8546 8547Syntax: 8548""""""" 8549 8550:: 8551 8552 store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.group !<index>] ; yields void 8553 store atomic [volatile] <ty> <value>, <ty>* <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<index>] ; yields void 8554 8555Overview: 8556""""""""" 8557 8558The '``store``' instruction is used to write to memory. 8559 8560Arguments: 8561"""""""""" 8562 8563There are two arguments to the ``store`` instruction: a value to store and an 8564address at which to store it. The type of the ``<pointer>`` operand must be a 8565pointer to the :ref:`first class <t_firstclass>` type of the ``<value>`` 8566operand. If the ``store`` is marked as ``volatile``, then the optimizer is not 8567allowed to modify the number or order of execution of this ``store`` with other 8568:ref:`volatile operations <volatile>`. Only values of :ref:`first class 8569<t_firstclass>` types of known size (i.e. not containing an :ref:`opaque 8570structural type <t_opaque>`) can be stored. 8571 8572If the ``store`` is marked as ``atomic``, it takes an extra :ref:`ordering 8573<ordering>` and optional ``syncscope("<target-scope>")`` argument. The 8574``acquire`` and ``acq_rel`` orderings aren't valid on ``store`` instructions. 8575Atomic loads produce :ref:`defined <memmodel>` results when they may see 8576multiple atomic stores. The type of the pointee must be an integer, pointer, or 8577floating-point type whose bit width is a power of two greater than or equal to 8578eight and less than or equal to a target-specific size limit. ``align`` must be 8579explicitly specified on atomic stores, and the store has undefined behavior if 8580the alignment is not set to a value which is at least the size in bytes of the 8581pointee. ``!nontemporal`` does not have any defined semantics for atomic stores. 8582 8583The optional constant ``align`` argument specifies the alignment of the 8584operation (that is, the alignment of the memory address). A value of 0 8585or an omitted ``align`` argument means that the operation has the ABI 8586alignment for the target. It is the responsibility of the code emitter 8587to ensure that the alignment information is correct. Overestimating the 8588alignment results in undefined behavior. Underestimating the 8589alignment may produce less efficient code. An alignment of 1 is always 8590safe. The maximum possible alignment is ``1 << 29``. An alignment 8591value higher than the size of the stored type implies memory up to the 8592alignment value bytes can be stored to without trapping in the default 8593address space. Storing to the higher bytes however may result in data 8594races if another thread can access the same address. Introducing a 8595data race is not allowed. Storing to the extra bytes is not allowed 8596even in situations where a data race is known to not exist if the 8597function has the ``sanitize_address`` attribute. 8598 8599The optional ``!nontemporal`` metadata must reference a single metadata 8600name ``<index>`` corresponding to a metadata node with one ``i32`` entry of 8601value 1. The existence of the ``!nontemporal`` metadata on the instruction 8602tells the optimizer and code generator that this load is not expected to 8603be reused in the cache. The code generator may select special 8604instructions to save cache bandwidth, such as the ``MOVNT`` instruction on 8605x86. 8606 8607The optional ``!invariant.group`` metadata must reference a 8608single metadata name ``<index>``. See ``invariant.group`` metadata. 8609 8610Semantics: 8611"""""""""" 8612 8613The contents of memory are updated to contain ``<value>`` at the 8614location specified by the ``<pointer>`` operand. If ``<value>`` is 8615of scalar type then the number of bytes written does not exceed the 8616minimum number of bytes needed to hold all bits of the type. For 8617example, storing an ``i24`` writes at most three bytes. When writing a 8618value of a type like ``i20`` with a size that is not an integral number 8619of bytes, it is unspecified what happens to the extra bits that do not 8620belong to the type, but they will typically be overwritten. 8621 8622Example: 8623"""""""" 8624 8625.. code-block:: llvm 8626 8627 %ptr = alloca i32 ; yields i32*:ptr 8628 store i32 3, i32* %ptr ; yields void 8629 %val = load i32, i32* %ptr ; yields i32:val = i32 3 8630 8631.. _i_fence: 8632 8633'``fence``' Instruction 8634^^^^^^^^^^^^^^^^^^^^^^^ 8635 8636Syntax: 8637""""""" 8638 8639:: 8640 8641 fence [syncscope("<target-scope>")] <ordering> ; yields void 8642 8643Overview: 8644""""""""" 8645 8646The '``fence``' instruction is used to introduce happens-before edges 8647between operations. 8648 8649Arguments: 8650"""""""""" 8651 8652'``fence``' instructions take an :ref:`ordering <ordering>` argument which 8653defines what *synchronizes-with* edges they add. They can only be given 8654``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings. 8655 8656Semantics: 8657"""""""""" 8658 8659A fence A which has (at least) ``release`` ordering semantics 8660*synchronizes with* a fence B with (at least) ``acquire`` ordering 8661semantics if and only if there exist atomic operations X and Y, both 8662operating on some atomic object M, such that A is sequenced before X, X 8663modifies M (either directly or through some side effect of a sequence 8664headed by X), Y is sequenced before B, and Y observes M. This provides a 8665*happens-before* dependency between A and B. Rather than an explicit 8666``fence``, one (but not both) of the atomic operations X or Y might 8667provide a ``release`` or ``acquire`` (resp.) ordering constraint and 8668still *synchronize-with* the explicit ``fence`` and establish the 8669*happens-before* edge. 8670 8671A ``fence`` which has ``seq_cst`` ordering, in addition to having both 8672``acquire`` and ``release`` semantics specified above, participates in 8673the global program order of other ``seq_cst`` operations and/or fences. 8674 8675A ``fence`` instruction can also take an optional 8676":ref:`syncscope <syncscope>`" argument. 8677 8678Example: 8679"""""""" 8680 8681.. code-block:: text 8682 8683 fence acquire ; yields void 8684 fence syncscope("singlethread") seq_cst ; yields void 8685 fence syncscope("agent") seq_cst ; yields void 8686 8687.. _i_cmpxchg: 8688 8689'``cmpxchg``' Instruction 8690^^^^^^^^^^^^^^^^^^^^^^^^^ 8691 8692Syntax: 8693""""""" 8694 8695:: 8696 8697 cmpxchg [weak] [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [syncscope("<target-scope>")] <success ordering> <failure ordering> ; yields { ty, i1 } 8698 8699Overview: 8700""""""""" 8701 8702The '``cmpxchg``' instruction is used to atomically modify memory. It 8703loads a value in memory and compares it to a given value. If they are 8704equal, it tries to store a new value into the memory. 8705 8706Arguments: 8707"""""""""" 8708 8709There are three arguments to the '``cmpxchg``' instruction: an address 8710to operate on, a value to compare to the value currently be at that 8711address, and a new value to place at that address if the compared values 8712are equal. The type of '<cmp>' must be an integer or pointer type whose 8713bit width is a power of two greater than or equal to eight and less 8714than or equal to a target-specific size limit. '<cmp>' and '<new>' must 8715have the same type, and the type of '<pointer>' must be a pointer to 8716that type. If the ``cmpxchg`` is marked as ``volatile``, then the 8717optimizer is not allowed to modify the number or order of execution of 8718this ``cmpxchg`` with other :ref:`volatile operations <volatile>`. 8719 8720The success and failure :ref:`ordering <ordering>` arguments specify how this 8721``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters 8722must be at least ``monotonic``, the ordering constraint on failure must be no 8723stronger than that on success, and the failure ordering cannot be either 8724``release`` or ``acq_rel``. 8725 8726A ``cmpxchg`` instruction can also take an optional 8727":ref:`syncscope <syncscope>`" argument. 8728 8729The pointer passed into cmpxchg must have alignment greater than or 8730equal to the size in memory of the operand. 8731 8732Semantics: 8733"""""""""" 8734 8735The contents of memory at the location specified by the '``<pointer>``' operand 8736is read and compared to '``<cmp>``'; if the values are equal, '``<new>``' is 8737written to the location. The original value at the location is returned, 8738together with a flag indicating success (true) or failure (false). 8739 8740If the cmpxchg operation is marked as ``weak`` then a spurious failure is 8741permitted: the operation may not write ``<new>`` even if the comparison 8742matched. 8743 8744If the cmpxchg operation is strong (the default), the i1 value is 1 if and only 8745if the value loaded equals ``cmp``. 8746 8747A successful ``cmpxchg`` is a read-modify-write instruction for the purpose of 8748identifying release sequences. A failed ``cmpxchg`` is equivalent to an atomic 8749load with an ordering parameter determined the second ordering parameter. 8750 8751Example: 8752"""""""" 8753 8754.. code-block:: llvm 8755 8756 entry: 8757 %orig = load atomic i32, i32* %ptr unordered, align 4 ; yields i32 8758 br label %loop 8759 8760 loop: 8761 %cmp = phi i32 [ %orig, %entry ], [%value_loaded, %loop] 8762 %squared = mul i32 %cmp, %cmp 8763 %val_success = cmpxchg i32* %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields { i32, i1 } 8764 %value_loaded = extractvalue { i32, i1 } %val_success, 0 8765 %success = extractvalue { i32, i1 } %val_success, 1 8766 br i1 %success, label %done, label %loop 8767 8768 done: 8769 ... 8770 8771.. _i_atomicrmw: 8772 8773'``atomicrmw``' Instruction 8774^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8775 8776Syntax: 8777""""""" 8778 8779:: 8780 8781 atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [syncscope("<target-scope>")] <ordering> ; yields ty 8782 8783Overview: 8784""""""""" 8785 8786The '``atomicrmw``' instruction is used to atomically modify memory. 8787 8788Arguments: 8789"""""""""" 8790 8791There are three arguments to the '``atomicrmw``' instruction: an 8792operation to apply, an address whose value to modify, an argument to the 8793operation. The operation must be one of the following keywords: 8794 8795- xchg 8796- add 8797- sub 8798- and 8799- nand 8800- or 8801- xor 8802- max 8803- min 8804- umax 8805- umin 8806- fadd 8807- fsub 8808 8809For most of these operations, the type of '<value>' must be an integer 8810type whose bit width is a power of two greater than or equal to eight 8811and less than or equal to a target-specific size limit. For xchg, this 8812may also be a floating point type with the same size constraints as 8813integers. For fadd/fsub, this must be a floating point type. The 8814type of the '``<pointer>``' operand must be a pointer to that type. If 8815the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not 8816allowed to modify the number or order of execution of this 8817``atomicrmw`` with other :ref:`volatile operations <volatile>`. 8818 8819A ``atomicrmw`` instruction can also take an optional 8820":ref:`syncscope <syncscope>`" argument. 8821 8822Semantics: 8823"""""""""" 8824 8825The contents of memory at the location specified by the '``<pointer>``' 8826operand are atomically read, modified, and written back. The original 8827value at the location is returned. The modification is specified by the 8828operation argument: 8829 8830- xchg: ``*ptr = val`` 8831- add: ``*ptr = *ptr + val`` 8832- sub: ``*ptr = *ptr - val`` 8833- and: ``*ptr = *ptr & val`` 8834- nand: ``*ptr = ~(*ptr & val)`` 8835- or: ``*ptr = *ptr | val`` 8836- xor: ``*ptr = *ptr ^ val`` 8837- max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison) 8838- min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison) 8839- umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned 8840 comparison) 8841- umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned 8842 comparison) 8843- fadd: ``*ptr = *ptr + val`` (using floating point arithmetic) 8844- fsub: ``*ptr = *ptr - val`` (using floating point arithmetic) 8845 8846Example: 8847"""""""" 8848 8849.. code-block:: llvm 8850 8851 %old = atomicrmw add i32* %ptr, i32 1 acquire ; yields i32 8852 8853.. _i_getelementptr: 8854 8855'``getelementptr``' Instruction 8856^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8857 8858Syntax: 8859""""""" 8860 8861:: 8862 8863 <result> = getelementptr <ty>, <ty>* <ptrval>{, [inrange] <ty> <idx>}* 8864 <result> = getelementptr inbounds <ty>, <ty>* <ptrval>{, [inrange] <ty> <idx>}* 8865 <result> = getelementptr <ty>, <ptr vector> <ptrval>, [inrange] <vector index type> <idx> 8866 8867Overview: 8868""""""""" 8869 8870The '``getelementptr``' instruction is used to get the address of a 8871subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs 8872address calculation only and does not access memory. The instruction can also 8873be used to calculate a vector of such addresses. 8874 8875Arguments: 8876"""""""""" 8877 8878The first argument is always a type used as the basis for the calculations. 8879The second argument is always a pointer or a vector of pointers, and is the 8880base address to start from. The remaining arguments are indices 8881that indicate which of the elements of the aggregate object are indexed. 8882The interpretation of each index is dependent on the type being indexed 8883into. The first index always indexes the pointer value given as the 8884second argument, the second index indexes a value of the type pointed to 8885(not necessarily the value directly pointed to, since the first index 8886can be non-zero), etc. The first type indexed into must be a pointer 8887value, subsequent types can be arrays, vectors, and structs. Note that 8888subsequent types being indexed into can never be pointers, since that 8889would require loading the pointer before continuing calculation. 8890 8891The type of each index argument depends on the type it is indexing into. 8892When indexing into a (optionally packed) structure, only ``i32`` integer 8893**constants** are allowed (when using a vector of indices they must all 8894be the **same** ``i32`` integer constant). When indexing into an array, 8895pointer or vector, integers of any width are allowed, and they are not 8896required to be constant. These integers are treated as signed values 8897where relevant. 8898 8899For example, let's consider a C code fragment and how it gets compiled 8900to LLVM: 8901 8902.. code-block:: c 8903 8904 struct RT { 8905 char A; 8906 int B[10][20]; 8907 char C; 8908 }; 8909 struct ST { 8910 int X; 8911 double Y; 8912 struct RT Z; 8913 }; 8914 8915 int *foo(struct ST *s) { 8916 return &s[1].Z.B[5][13]; 8917 } 8918 8919The LLVM code generated by Clang is: 8920 8921.. code-block:: llvm 8922 8923 %struct.RT = type { i8, [10 x [20 x i32]], i8 } 8924 %struct.ST = type { i32, double, %struct.RT } 8925 8926 define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp { 8927 entry: 8928 %arrayidx = getelementptr inbounds %struct.ST, %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13 8929 ret i32* %arrayidx 8930 } 8931 8932Semantics: 8933"""""""""" 8934 8935In the example above, the first index is indexing into the 8936'``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``' 8937= '``{ i32, double, %struct.RT }``' type, a structure. The second index 8938indexes into the third element of the structure, yielding a 8939'``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another 8940structure. The third index indexes into the second element of the 8941structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two 8942dimensions of the array are subscripted into, yielding an '``i32``' 8943type. The '``getelementptr``' instruction returns a pointer to this 8944element, thus computing a value of '``i32*``' type. 8945 8946Note that it is perfectly legal to index partially through a structure, 8947returning a pointer to an inner element. Because of this, the LLVM code 8948for the given testcase is equivalent to: 8949 8950.. code-block:: llvm 8951 8952 define i32* @foo(%struct.ST* %s) { 8953 %t1 = getelementptr %struct.ST, %struct.ST* %s, i32 1 ; yields %struct.ST*:%t1 8954 %t2 = getelementptr %struct.ST, %struct.ST* %t1, i32 0, i32 2 ; yields %struct.RT*:%t2 8955 %t3 = getelementptr %struct.RT, %struct.RT* %t2, i32 0, i32 1 ; yields [10 x [20 x i32]]*:%t3 8956 %t4 = getelementptr [10 x [20 x i32]], [10 x [20 x i32]]* %t3, i32 0, i32 5 ; yields [20 x i32]*:%t4 8957 %t5 = getelementptr [20 x i32], [20 x i32]* %t4, i32 0, i32 13 ; yields i32*:%t5 8958 ret i32* %t5 8959 } 8960 8961If the ``inbounds`` keyword is present, the result value of the 8962``getelementptr`` is a :ref:`poison value <poisonvalues>` if the base 8963pointer is not an *in bounds* address of an allocated object, or if any 8964of the addresses that would be formed by successive addition of the 8965offsets implied by the indices to the base address with infinitely 8966precise signed arithmetic are not an *in bounds* address of that 8967allocated object. The *in bounds* addresses for an allocated object are 8968all the addresses that point into the object, plus the address one byte 8969past the end. The only *in bounds* address for a null pointer in the 8970default address-space is the null pointer itself. In cases where the 8971base is a vector of pointers the ``inbounds`` keyword applies to each 8972of the computations element-wise. 8973 8974If the ``inbounds`` keyword is not present, the offsets are added to the 8975base address with silently-wrapping two's complement arithmetic. If the 8976offsets have a different width from the pointer, they are sign-extended 8977or truncated to the width of the pointer. The result value of the 8978``getelementptr`` may be outside the object pointed to by the base 8979pointer. The result value may not necessarily be used to access memory 8980though, even if it happens to point into allocated storage. See the 8981:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more 8982information. 8983 8984If the ``inrange`` keyword is present before any index, loading from or 8985storing to any pointer derived from the ``getelementptr`` has undefined 8986behavior if the load or store would access memory outside of the bounds of 8987the element selected by the index marked as ``inrange``. The result of a 8988pointer comparison or ``ptrtoint`` (including ``ptrtoint``-like operations 8989involving memory) involving a pointer derived from a ``getelementptr`` with 8990the ``inrange`` keyword is undefined, with the exception of comparisons 8991in the case where both operands are in the range of the element selected 8992by the ``inrange`` keyword, inclusive of the address one past the end of 8993that element. Note that the ``inrange`` keyword is currently only allowed 8994in constant ``getelementptr`` expressions. 8995 8996The getelementptr instruction is often confusing. For some more insight 8997into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`. 8998 8999Example: 9000"""""""" 9001 9002.. code-block:: llvm 9003 9004 ; yields [12 x i8]*:aptr 9005 %aptr = getelementptr {i32, [12 x i8]}, {i32, [12 x i8]}* %saptr, i64 0, i32 1 9006 ; yields i8*:vptr 9007 %vptr = getelementptr {i32, <2 x i8>}, {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1 9008 ; yields i8*:eptr 9009 %eptr = getelementptr [12 x i8], [12 x i8]* %aptr, i64 0, i32 1 9010 ; yields i32*:iptr 9011 %iptr = getelementptr [10 x i32], [10 x i32]* @arr, i16 0, i16 0 9012 9013Vector of pointers: 9014""""""""""""""""""" 9015 9016The ``getelementptr`` returns a vector of pointers, instead of a single address, 9017when one or more of its arguments is a vector. In such cases, all vector 9018arguments should have the same number of elements, and every scalar argument 9019will be effectively broadcast into a vector during address calculation. 9020 9021.. code-block:: llvm 9022 9023 ; All arguments are vectors: 9024 ; A[i] = ptrs[i] + offsets[i]*sizeof(i8) 9025 %A = getelementptr i8, <4 x i8*> %ptrs, <4 x i64> %offsets 9026 9027 ; Add the same scalar offset to each pointer of a vector: 9028 ; A[i] = ptrs[i] + offset*sizeof(i8) 9029 %A = getelementptr i8, <4 x i8*> %ptrs, i64 %offset 9030 9031 ; Add distinct offsets to the same pointer: 9032 ; A[i] = ptr + offsets[i]*sizeof(i8) 9033 %A = getelementptr i8, i8* %ptr, <4 x i64> %offsets 9034 9035 ; In all cases described above the type of the result is <4 x i8*> 9036 9037The two following instructions are equivalent: 9038 9039.. code-block:: llvm 9040 9041 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1, 9042 <4 x i32> <i32 2, i32 2, i32 2, i32 2>, 9043 <4 x i32> <i32 1, i32 1, i32 1, i32 1>, 9044 <4 x i32> %ind4, 9045 <4 x i64> <i64 13, i64 13, i64 13, i64 13> 9046 9047 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1, 9048 i32 2, i32 1, <4 x i32> %ind4, i64 13 9049 9050Let's look at the C code, where the vector version of ``getelementptr`` 9051makes sense: 9052 9053.. code-block:: c 9054 9055 // Let's assume that we vectorize the following loop: 9056 double *A, *B; int *C; 9057 for (int i = 0; i < size; ++i) { 9058 A[i] = B[C[i]]; 9059 } 9060 9061.. code-block:: llvm 9062 9063 ; get pointers for 8 elements from array B 9064 %ptrs = getelementptr double, double* %B, <8 x i32> %C 9065 ; load 8 elements from array B into A 9066 %A = call <8 x double> @llvm.masked.gather.v8f64.v8p0f64(<8 x double*> %ptrs, 9067 i32 8, <8 x i1> %mask, <8 x double> %passthru) 9068 9069Conversion Operations 9070--------------------- 9071 9072The instructions in this category are the conversion instructions 9073(casting) which all take a single operand and a type. They perform 9074various bit conversions on the operand. 9075 9076.. _i_trunc: 9077 9078'``trunc .. to``' Instruction 9079^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9080 9081Syntax: 9082""""""" 9083 9084:: 9085 9086 <result> = trunc <ty> <value> to <ty2> ; yields ty2 9087 9088Overview: 9089""""""""" 9090 9091The '``trunc``' instruction truncates its operand to the type ``ty2``. 9092 9093Arguments: 9094"""""""""" 9095 9096The '``trunc``' instruction takes a value to trunc, and a type to trunc 9097it to. Both types must be of :ref:`integer <t_integer>` types, or vectors 9098of the same number of integers. The bit size of the ``value`` must be 9099larger than the bit size of the destination type, ``ty2``. Equal sized 9100types are not allowed. 9101 9102Semantics: 9103"""""""""" 9104 9105The '``trunc``' instruction truncates the high order bits in ``value`` 9106and converts the remaining bits to ``ty2``. Since the source size must 9107be larger than the destination size, ``trunc`` cannot be a *no-op cast*. 9108It will always truncate bits. 9109 9110Example: 9111"""""""" 9112 9113.. code-block:: llvm 9114 9115 %X = trunc i32 257 to i8 ; yields i8:1 9116 %Y = trunc i32 123 to i1 ; yields i1:true 9117 %Z = trunc i32 122 to i1 ; yields i1:false 9118 %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7> 9119 9120.. _i_zext: 9121 9122'``zext .. to``' Instruction 9123^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9124 9125Syntax: 9126""""""" 9127 9128:: 9129 9130 <result> = zext <ty> <value> to <ty2> ; yields ty2 9131 9132Overview: 9133""""""""" 9134 9135The '``zext``' instruction zero extends its operand to type ``ty2``. 9136 9137Arguments: 9138"""""""""" 9139 9140The '``zext``' instruction takes a value to cast, and a type to cast it 9141to. Both types must be of :ref:`integer <t_integer>` types, or vectors of 9142the same number of integers. The bit size of the ``value`` must be 9143smaller than the bit size of the destination type, ``ty2``. 9144 9145Semantics: 9146"""""""""" 9147 9148The ``zext`` fills the high order bits of the ``value`` with zero bits 9149until it reaches the size of the destination type, ``ty2``. 9150 9151When zero extending from i1, the result will always be either 0 or 1. 9152 9153Example: 9154"""""""" 9155 9156.. code-block:: llvm 9157 9158 %X = zext i32 257 to i64 ; yields i64:257 9159 %Y = zext i1 true to i32 ; yields i32:1 9160 %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> 9161 9162.. _i_sext: 9163 9164'``sext .. to``' Instruction 9165^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9166 9167Syntax: 9168""""""" 9169 9170:: 9171 9172 <result> = sext <ty> <value> to <ty2> ; yields ty2 9173 9174Overview: 9175""""""""" 9176 9177The '``sext``' sign extends ``value`` to the type ``ty2``. 9178 9179Arguments: 9180"""""""""" 9181 9182The '``sext``' instruction takes a value to cast, and a type to cast it 9183to. Both types must be of :ref:`integer <t_integer>` types, or vectors of 9184the same number of integers. The bit size of the ``value`` must be 9185smaller than the bit size of the destination type, ``ty2``. 9186 9187Semantics: 9188"""""""""" 9189 9190The '``sext``' instruction performs a sign extension by copying the sign 9191bit (highest order bit) of the ``value`` until it reaches the bit size 9192of the type ``ty2``. 9193 9194When sign extending from i1, the extension always results in -1 or 0. 9195 9196Example: 9197"""""""" 9198 9199.. code-block:: llvm 9200 9201 %X = sext i8 -1 to i16 ; yields i16 :65535 9202 %Y = sext i1 true to i32 ; yields i32:-1 9203 %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> 9204 9205'``fptrunc .. to``' Instruction 9206^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9207 9208Syntax: 9209""""""" 9210 9211:: 9212 9213 <result> = fptrunc <ty> <value> to <ty2> ; yields ty2 9214 9215Overview: 9216""""""""" 9217 9218The '``fptrunc``' instruction truncates ``value`` to type ``ty2``. 9219 9220Arguments: 9221"""""""""" 9222 9223The '``fptrunc``' instruction takes a :ref:`floating-point <t_floating>` 9224value to cast and a :ref:`floating-point <t_floating>` type to cast it to. 9225The size of ``value`` must be larger than the size of ``ty2``. This 9226implies that ``fptrunc`` cannot be used to make a *no-op cast*. 9227 9228Semantics: 9229"""""""""" 9230 9231The '``fptrunc``' instruction casts a ``value`` from a larger 9232:ref:`floating-point <t_floating>` type to a smaller :ref:`floating-point 9233<t_floating>` type. 9234This instruction is assumed to execute in the default :ref:`floating-point 9235environment <floatenv>`. 9236 9237Example: 9238"""""""" 9239 9240.. code-block:: llvm 9241 9242 %X = fptrunc double 16777217.0 to float ; yields float:16777216.0 9243 %Y = fptrunc double 1.0E+300 to half ; yields half:+infinity 9244 9245'``fpext .. to``' Instruction 9246^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9247 9248Syntax: 9249""""""" 9250 9251:: 9252 9253 <result> = fpext <ty> <value> to <ty2> ; yields ty2 9254 9255Overview: 9256""""""""" 9257 9258The '``fpext``' extends a floating-point ``value`` to a larger floating-point 9259value. 9260 9261Arguments: 9262"""""""""" 9263 9264The '``fpext``' instruction takes a :ref:`floating-point <t_floating>` 9265``value`` to cast, and a :ref:`floating-point <t_floating>` type to cast it 9266to. The source type must be smaller than the destination type. 9267 9268Semantics: 9269"""""""""" 9270 9271The '``fpext``' instruction extends the ``value`` from a smaller 9272:ref:`floating-point <t_floating>` type to a larger :ref:`floating-point 9273<t_floating>` type. The ``fpext`` cannot be used to make a 9274*no-op cast* because it always changes bits. Use ``bitcast`` to make a 9275*no-op cast* for a floating-point cast. 9276 9277Example: 9278"""""""" 9279 9280.. code-block:: llvm 9281 9282 %X = fpext float 3.125 to double ; yields double:3.125000e+00 9283 %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000 9284 9285'``fptoui .. to``' Instruction 9286^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9287 9288Syntax: 9289""""""" 9290 9291:: 9292 9293 <result> = fptoui <ty> <value> to <ty2> ; yields ty2 9294 9295Overview: 9296""""""""" 9297 9298The '``fptoui``' converts a floating-point ``value`` to its unsigned 9299integer equivalent of type ``ty2``. 9300 9301Arguments: 9302"""""""""" 9303 9304The '``fptoui``' instruction takes a value to cast, which must be a 9305scalar or vector :ref:`floating-point <t_floating>` value, and a type to 9306cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If 9307``ty`` is a vector floating-point type, ``ty2`` must be a vector integer 9308type with the same number of elements as ``ty`` 9309 9310Semantics: 9311"""""""""" 9312 9313The '``fptoui``' instruction converts its :ref:`floating-point 9314<t_floating>` operand into the nearest (rounding towards zero) 9315unsigned integer value. If the value cannot fit in ``ty2``, the result 9316is a :ref:`poison value <poisonvalues>`. 9317 9318Example: 9319"""""""" 9320 9321.. code-block:: llvm 9322 9323 %X = fptoui double 123.0 to i32 ; yields i32:123 9324 %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1 9325 %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1 9326 9327'``fptosi .. to``' Instruction 9328^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9329 9330Syntax: 9331""""""" 9332 9333:: 9334 9335 <result> = fptosi <ty> <value> to <ty2> ; yields ty2 9336 9337Overview: 9338""""""""" 9339 9340The '``fptosi``' instruction converts :ref:`floating-point <t_floating>` 9341``value`` to type ``ty2``. 9342 9343Arguments: 9344"""""""""" 9345 9346The '``fptosi``' instruction takes a value to cast, which must be a 9347scalar or vector :ref:`floating-point <t_floating>` value, and a type to 9348cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If 9349``ty`` is a vector floating-point type, ``ty2`` must be a vector integer 9350type with the same number of elements as ``ty`` 9351 9352Semantics: 9353"""""""""" 9354 9355The '``fptosi``' instruction converts its :ref:`floating-point 9356<t_floating>` operand into the nearest (rounding towards zero) 9357signed integer value. If the value cannot fit in ``ty2``, the result 9358is a :ref:`poison value <poisonvalues>`. 9359 9360Example: 9361"""""""" 9362 9363.. code-block:: llvm 9364 9365 %X = fptosi double -123.0 to i32 ; yields i32:-123 9366 %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1 9367 %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1 9368 9369'``uitofp .. to``' Instruction 9370^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9371 9372Syntax: 9373""""""" 9374 9375:: 9376 9377 <result> = uitofp <ty> <value> to <ty2> ; yields ty2 9378 9379Overview: 9380""""""""" 9381 9382The '``uitofp``' instruction regards ``value`` as an unsigned integer 9383and converts that value to the ``ty2`` type. 9384 9385Arguments: 9386"""""""""" 9387 9388The '``uitofp``' instruction takes a value to cast, which must be a 9389scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to 9390``ty2``, which must be an :ref:`floating-point <t_floating>` type. If 9391``ty`` is a vector integer type, ``ty2`` must be a vector floating-point 9392type with the same number of elements as ``ty`` 9393 9394Semantics: 9395"""""""""" 9396 9397The '``uitofp``' instruction interprets its operand as an unsigned 9398integer quantity and converts it to the corresponding floating-point 9399value. If the value cannot be exactly represented, it is rounded using 9400the default rounding mode. 9401 9402 9403Example: 9404"""""""" 9405 9406.. code-block:: llvm 9407 9408 %X = uitofp i32 257 to float ; yields float:257.0 9409 %Y = uitofp i8 -1 to double ; yields double:255.0 9410 9411'``sitofp .. to``' Instruction 9412^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9413 9414Syntax: 9415""""""" 9416 9417:: 9418 9419 <result> = sitofp <ty> <value> to <ty2> ; yields ty2 9420 9421Overview: 9422""""""""" 9423 9424The '``sitofp``' instruction regards ``value`` as a signed integer and 9425converts that value to the ``ty2`` type. 9426 9427Arguments: 9428"""""""""" 9429 9430The '``sitofp``' instruction takes a value to cast, which must be a 9431scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to 9432``ty2``, which must be an :ref:`floating-point <t_floating>` type. If 9433``ty`` is a vector integer type, ``ty2`` must be a vector floating-point 9434type with the same number of elements as ``ty`` 9435 9436Semantics: 9437"""""""""" 9438 9439The '``sitofp``' instruction interprets its operand as a signed integer 9440quantity and converts it to the corresponding floating-point value. If the 9441value cannot be exactly represented, it is rounded using the default rounding 9442mode. 9443 9444Example: 9445"""""""" 9446 9447.. code-block:: llvm 9448 9449 %X = sitofp i32 257 to float ; yields float:257.0 9450 %Y = sitofp i8 -1 to double ; yields double:-1.0 9451 9452.. _i_ptrtoint: 9453 9454'``ptrtoint .. to``' Instruction 9455^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9456 9457Syntax: 9458""""""" 9459 9460:: 9461 9462 <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2 9463 9464Overview: 9465""""""""" 9466 9467The '``ptrtoint``' instruction converts the pointer or a vector of 9468pointers ``value`` to the integer (or vector of integers) type ``ty2``. 9469 9470Arguments: 9471"""""""""" 9472 9473The '``ptrtoint``' instruction takes a ``value`` to cast, which must be 9474a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a 9475type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or 9476a vector of integers type. 9477 9478Semantics: 9479"""""""""" 9480 9481The '``ptrtoint``' instruction converts ``value`` to integer type 9482``ty2`` by interpreting the pointer value as an integer and either 9483truncating or zero extending that value to the size of the integer type. 9484If ``value`` is smaller than ``ty2`` then a zero extension is done. If 9485``value`` is larger than ``ty2`` then a truncation is done. If they are 9486the same size, then nothing is done (*no-op cast*) other than a type 9487change. 9488 9489Example: 9490"""""""" 9491 9492.. code-block:: llvm 9493 9494 %X = ptrtoint i32* %P to i8 ; yields truncation on 32-bit architecture 9495 %Y = ptrtoint i32* %P to i64 ; yields zero extension on 32-bit architecture 9496 %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture 9497 9498.. _i_inttoptr: 9499 9500'``inttoptr .. to``' Instruction 9501^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9502 9503Syntax: 9504""""""" 9505 9506:: 9507 9508 <result> = inttoptr <ty> <value> to <ty2> ; yields ty2 9509 9510Overview: 9511""""""""" 9512 9513The '``inttoptr``' instruction converts an integer ``value`` to a 9514pointer type, ``ty2``. 9515 9516Arguments: 9517"""""""""" 9518 9519The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to 9520cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>` 9521type. 9522 9523Semantics: 9524"""""""""" 9525 9526The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by 9527applying either a zero extension or a truncation depending on the size 9528of the integer ``value``. If ``value`` is larger than the size of a 9529pointer then a truncation is done. If ``value`` is smaller than the size 9530of a pointer then a zero extension is done. If they are the same size, 9531nothing is done (*no-op cast*). 9532 9533Example: 9534"""""""" 9535 9536.. code-block:: llvm 9537 9538 %X = inttoptr i32 255 to i32* ; yields zero extension on 64-bit architecture 9539 %Y = inttoptr i32 255 to i32* ; yields no-op on 32-bit architecture 9540 %Z = inttoptr i64 0 to i32* ; yields truncation on 32-bit architecture 9541 %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers 9542 9543.. _i_bitcast: 9544 9545'``bitcast .. to``' Instruction 9546^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9547 9548Syntax: 9549""""""" 9550 9551:: 9552 9553 <result> = bitcast <ty> <value> to <ty2> ; yields ty2 9554 9555Overview: 9556""""""""" 9557 9558The '``bitcast``' instruction converts ``value`` to type ``ty2`` without 9559changing any bits. 9560 9561Arguments: 9562"""""""""" 9563 9564The '``bitcast``' instruction takes a value to cast, which must be a 9565non-aggregate first class value, and a type to cast it to, which must 9566also be a non-aggregate :ref:`first class <t_firstclass>` type. The 9567bit sizes of ``value`` and the destination type, ``ty2``, must be 9568identical. If the source type is a pointer, the destination type must 9569also be a pointer of the same size. This instruction supports bitwise 9570conversion of vectors to integers and to vectors of other types (as 9571long as they have the same size). 9572 9573Semantics: 9574"""""""""" 9575 9576The '``bitcast``' instruction converts ``value`` to type ``ty2``. It 9577is always a *no-op cast* because no bits change with this 9578conversion. The conversion is done as if the ``value`` had been stored 9579to memory and read back as type ``ty2``. Pointer (or vector of 9580pointers) types may only be converted to other pointer (or vector of 9581pointers) types with the same address space through this instruction. 9582To convert pointers to other types, use the :ref:`inttoptr <i_inttoptr>` 9583or :ref:`ptrtoint <i_ptrtoint>` instructions first. 9584 9585Example: 9586"""""""" 9587 9588.. code-block:: text 9589 9590 %X = bitcast i8 255 to i8 ; yields i8 :-1 9591 %Y = bitcast i32* %x to sint* ; yields sint*:%x 9592 %Z = bitcast <2 x int> %V to i64; ; yields i64: %V 9593 %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*> 9594 9595.. _i_addrspacecast: 9596 9597'``addrspacecast .. to``' Instruction 9598^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9599 9600Syntax: 9601""""""" 9602 9603:: 9604 9605 <result> = addrspacecast <pty> <ptrval> to <pty2> ; yields pty2 9606 9607Overview: 9608""""""""" 9609 9610The '``addrspacecast``' instruction converts ``ptrval`` from ``pty`` in 9611address space ``n`` to type ``pty2`` in address space ``m``. 9612 9613Arguments: 9614"""""""""" 9615 9616The '``addrspacecast``' instruction takes a pointer or vector of pointer value 9617to cast and a pointer type to cast it to, which must have a different 9618address space. 9619 9620Semantics: 9621"""""""""" 9622 9623The '``addrspacecast``' instruction converts the pointer value 9624``ptrval`` to type ``pty2``. It can be a *no-op cast* or a complex 9625value modification, depending on the target and the address space 9626pair. Pointer conversions within the same address space must be 9627performed with the ``bitcast`` instruction. Note that if the address space 9628conversion is legal then both result and operand refer to the same memory 9629location. 9630 9631Example: 9632"""""""" 9633 9634.. code-block:: llvm 9635 9636 %X = addrspacecast i32* %x to i32 addrspace(1)* ; yields i32 addrspace(1)*:%x 9637 %Y = addrspacecast i32 addrspace(1)* %y to i64 addrspace(2)* ; yields i64 addrspace(2)*:%y 9638 %Z = addrspacecast <4 x i32*> %z to <4 x float addrspace(3)*> ; yields <4 x float addrspace(3)*>:%z 9639 9640.. _otherops: 9641 9642Other Operations 9643---------------- 9644 9645The instructions in this category are the "miscellaneous" instructions, 9646which defy better classification. 9647 9648.. _i_icmp: 9649 9650'``icmp``' Instruction 9651^^^^^^^^^^^^^^^^^^^^^^ 9652 9653Syntax: 9654""""""" 9655 9656:: 9657 9658 <result> = icmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result 9659 9660Overview: 9661""""""""" 9662 9663The '``icmp``' instruction returns a boolean value or a vector of 9664boolean values based on comparison of its two integer, integer vector, 9665pointer, or pointer vector operands. 9666 9667Arguments: 9668"""""""""" 9669 9670The '``icmp``' instruction takes three operands. The first operand is 9671the condition code indicating the kind of comparison to perform. It is 9672not a value, just a keyword. The possible condition codes are: 9673 9674#. ``eq``: equal 9675#. ``ne``: not equal 9676#. ``ugt``: unsigned greater than 9677#. ``uge``: unsigned greater or equal 9678#. ``ult``: unsigned less than 9679#. ``ule``: unsigned less or equal 9680#. ``sgt``: signed greater than 9681#. ``sge``: signed greater or equal 9682#. ``slt``: signed less than 9683#. ``sle``: signed less or equal 9684 9685The remaining two arguments must be :ref:`integer <t_integer>` or 9686:ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They 9687must also be identical types. 9688 9689Semantics: 9690"""""""""" 9691 9692The '``icmp``' compares ``op1`` and ``op2`` according to the condition 9693code given as ``cond``. The comparison performed always yields either an 9694:ref:`i1 <t_integer>` or vector of ``i1`` result, as follows: 9695 9696#. ``eq``: yields ``true`` if the operands are equal, ``false`` 9697 otherwise. No sign interpretation is necessary or performed. 9698#. ``ne``: yields ``true`` if the operands are unequal, ``false`` 9699 otherwise. No sign interpretation is necessary or performed. 9700#. ``ugt``: interprets the operands as unsigned values and yields 9701 ``true`` if ``op1`` is greater than ``op2``. 9702#. ``uge``: interprets the operands as unsigned values and yields 9703 ``true`` if ``op1`` is greater than or equal to ``op2``. 9704#. ``ult``: interprets the operands as unsigned values and yields 9705 ``true`` if ``op1`` is less than ``op2``. 9706#. ``ule``: interprets the operands as unsigned values and yields 9707 ``true`` if ``op1`` is less than or equal to ``op2``. 9708#. ``sgt``: interprets the operands as signed values and yields ``true`` 9709 if ``op1`` is greater than ``op2``. 9710#. ``sge``: interprets the operands as signed values and yields ``true`` 9711 if ``op1`` is greater than or equal to ``op2``. 9712#. ``slt``: interprets the operands as signed values and yields ``true`` 9713 if ``op1`` is less than ``op2``. 9714#. ``sle``: interprets the operands as signed values and yields ``true`` 9715 if ``op1`` is less than or equal to ``op2``. 9716 9717If the operands are :ref:`pointer <t_pointer>` typed, the pointer values 9718are compared as if they were integers. 9719 9720If the operands are integer vectors, then they are compared element by 9721element. The result is an ``i1`` vector with the same number of elements 9722as the values being compared. Otherwise, the result is an ``i1``. 9723 9724Example: 9725"""""""" 9726 9727.. code-block:: text 9728 9729 <result> = icmp eq i32 4, 5 ; yields: result=false 9730 <result> = icmp ne float* %X, %X ; yields: result=false 9731 <result> = icmp ult i16 4, 5 ; yields: result=true 9732 <result> = icmp sgt i16 4, 5 ; yields: result=false 9733 <result> = icmp ule i16 -4, 5 ; yields: result=false 9734 <result> = icmp sge i16 4, 5 ; yields: result=false 9735 9736.. _i_fcmp: 9737 9738'``fcmp``' Instruction 9739^^^^^^^^^^^^^^^^^^^^^^ 9740 9741Syntax: 9742""""""" 9743 9744:: 9745 9746 <result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result 9747 9748Overview: 9749""""""""" 9750 9751The '``fcmp``' instruction returns a boolean value or vector of boolean 9752values based on comparison of its operands. 9753 9754If the operands are floating-point scalars, then the result type is a 9755boolean (:ref:`i1 <t_integer>`). 9756 9757If the operands are floating-point vectors, then the result type is a 9758vector of boolean with the same number of elements as the operands being 9759compared. 9760 9761Arguments: 9762"""""""""" 9763 9764The '``fcmp``' instruction takes three operands. The first operand is 9765the condition code indicating the kind of comparison to perform. It is 9766not a value, just a keyword. The possible condition codes are: 9767 9768#. ``false``: no comparison, always returns false 9769#. ``oeq``: ordered and equal 9770#. ``ogt``: ordered and greater than 9771#. ``oge``: ordered and greater than or equal 9772#. ``olt``: ordered and less than 9773#. ``ole``: ordered and less than or equal 9774#. ``one``: ordered and not equal 9775#. ``ord``: ordered (no nans) 9776#. ``ueq``: unordered or equal 9777#. ``ugt``: unordered or greater than 9778#. ``uge``: unordered or greater than or equal 9779#. ``ult``: unordered or less than 9780#. ``ule``: unordered or less than or equal 9781#. ``une``: unordered or not equal 9782#. ``uno``: unordered (either nans) 9783#. ``true``: no comparison, always returns true 9784 9785*Ordered* means that neither operand is a QNAN while *unordered* means 9786that either operand may be a QNAN. 9787 9788Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating-point 9789<t_floating>` type or a :ref:`vector <t_vector>` of floating-point type. 9790They must have identical types. 9791 9792Semantics: 9793"""""""""" 9794 9795The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the 9796condition code given as ``cond``. If the operands are vectors, then the 9797vectors are compared element by element. Each comparison performed 9798always yields an :ref:`i1 <t_integer>` result, as follows: 9799 9800#. ``false``: always yields ``false``, regardless of operands. 9801#. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1`` 9802 is equal to ``op2``. 9803#. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1`` 9804 is greater than ``op2``. 9805#. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1`` 9806 is greater than or equal to ``op2``. 9807#. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1`` 9808 is less than ``op2``. 9809#. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1`` 9810 is less than or equal to ``op2``. 9811#. ``one``: yields ``true`` if both operands are not a QNAN and ``op1`` 9812 is not equal to ``op2``. 9813#. ``ord``: yields ``true`` if both operands are not a QNAN. 9814#. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is 9815 equal to ``op2``. 9816#. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is 9817 greater than ``op2``. 9818#. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is 9819 greater than or equal to ``op2``. 9820#. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is 9821 less than ``op2``. 9822#. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is 9823 less than or equal to ``op2``. 9824#. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is 9825 not equal to ``op2``. 9826#. ``uno``: yields ``true`` if either operand is a QNAN. 9827#. ``true``: always yields ``true``, regardless of operands. 9828 9829The ``fcmp`` instruction can also optionally take any number of 9830:ref:`fast-math flags <fastmath>`, which are optimization hints to enable 9831otherwise unsafe floating-point optimizations. 9832 9833Any set of fast-math flags are legal on an ``fcmp`` instruction, but the 9834only flags that have any effect on its semantics are those that allow 9835assumptions to be made about the values of input arguments; namely 9836``nnan``, ``ninf``, and ``reassoc``. See :ref:`fastmath` for more information. 9837 9838Example: 9839"""""""" 9840 9841.. code-block:: text 9842 9843 <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false 9844 <result> = fcmp one float 4.0, 5.0 ; yields: result=true 9845 <result> = fcmp olt float 4.0, 5.0 ; yields: result=true 9846 <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false 9847 9848.. _i_phi: 9849 9850'``phi``' Instruction 9851^^^^^^^^^^^^^^^^^^^^^ 9852 9853Syntax: 9854""""""" 9855 9856:: 9857 9858 <result> = phi <ty> [ <val0>, <label0>], ... 9859 9860Overview: 9861""""""""" 9862 9863The '``phi``' instruction is used to implement the φ node in the SSA 9864graph representing the function. 9865 9866Arguments: 9867"""""""""" 9868 9869The type of the incoming values is specified with the first type field. 9870After this, the '``phi``' instruction takes a list of pairs as 9871arguments, with one pair for each predecessor basic block of the current 9872block. Only values of :ref:`first class <t_firstclass>` type may be used as 9873the value arguments to the PHI node. Only labels may be used as the 9874label arguments. 9875 9876There must be no non-phi instructions between the start of a basic block 9877and the PHI instructions: i.e. PHI instructions must be first in a basic 9878block. 9879 9880For the purposes of the SSA form, the use of each incoming value is 9881deemed to occur on the edge from the corresponding predecessor block to 9882the current block (but after any definition of an '``invoke``' 9883instruction's return value on the same edge). 9884 9885Semantics: 9886"""""""""" 9887 9888At runtime, the '``phi``' instruction logically takes on the value 9889specified by the pair corresponding to the predecessor basic block that 9890executed just prior to the current block. 9891 9892Example: 9893"""""""" 9894 9895.. code-block:: llvm 9896 9897 Loop: ; Infinite loop that counts from 0 on up... 9898 %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ] 9899 %nextindvar = add i32 %indvar, 1 9900 br label %Loop 9901 9902.. _i_select: 9903 9904'``select``' Instruction 9905^^^^^^^^^^^^^^^^^^^^^^^^ 9906 9907Syntax: 9908""""""" 9909 9910:: 9911 9912 <result> = select selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty 9913 9914 selty is either i1 or {<N x i1>} 9915 9916Overview: 9917""""""""" 9918 9919The '``select``' instruction is used to choose one value based on a 9920condition, without IR-level branching. 9921 9922Arguments: 9923"""""""""" 9924 9925The '``select``' instruction requires an 'i1' value or a vector of 'i1' 9926values indicating the condition, and two values of the same :ref:`first 9927class <t_firstclass>` type. 9928 9929Semantics: 9930"""""""""" 9931 9932If the condition is an i1 and it evaluates to 1, the instruction returns 9933the first value argument; otherwise, it returns the second value 9934argument. 9935 9936If the condition is a vector of i1, then the value arguments must be 9937vectors of the same size, and the selection is done element by element. 9938 9939If the condition is an i1 and the value arguments are vectors of the 9940same size, then an entire vector is selected. 9941 9942Example: 9943"""""""" 9944 9945.. code-block:: llvm 9946 9947 %X = select i1 true, i8 17, i8 42 ; yields i8:17 9948 9949.. _i_call: 9950 9951'``call``' Instruction 9952^^^^^^^^^^^^^^^^^^^^^^ 9953 9954Syntax: 9955""""""" 9956 9957:: 9958 9959 <result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)] 9960 [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ] 9961 9962Overview: 9963""""""""" 9964 9965The '``call``' instruction represents a simple function call. 9966 9967Arguments: 9968"""""""""" 9969 9970This instruction requires several arguments: 9971 9972#. The optional ``tail`` and ``musttail`` markers indicate that the optimizers 9973 should perform tail call optimization. The ``tail`` marker is a hint that 9974 `can be ignored <CodeGenerator.html#sibcallopt>`_. The ``musttail`` marker 9975 means that the call must be tail call optimized in order for the program to 9976 be correct. The ``musttail`` marker provides these guarantees: 9977 9978 #. The call will not cause unbounded stack growth if it is part of a 9979 recursive cycle in the call graph. 9980 #. Arguments with the :ref:`inalloca <attr_inalloca>` attribute are 9981 forwarded in place. 9982 9983 Both markers imply that the callee does not access allocas from the caller. 9984 The ``tail`` marker additionally implies that the callee does not access 9985 varargs from the caller, while ``musttail`` implies that varargs from the 9986 caller are passed to the callee. Calls marked ``musttail`` must obey the 9987 following additional rules: 9988 9989 - The call must immediately precede a :ref:`ret <i_ret>` instruction, 9990 or a pointer bitcast followed by a ret instruction. 9991 - The ret instruction must return the (possibly bitcasted) value 9992 produced by the call or void. 9993 - The caller and callee prototypes must match. Pointer types of 9994 parameters or return types may differ in pointee type, but not 9995 in address space. 9996 - The calling conventions of the caller and callee must match. 9997 - All ABI-impacting function attributes, such as sret, byval, inreg, 9998 returned, and inalloca, must match. 9999 - The callee must be varargs iff the caller is varargs. Bitcasting a 10000 non-varargs function to the appropriate varargs type is legal so 10001 long as the non-varargs prefixes obey the other rules. 10002 10003 Tail call optimization for calls marked ``tail`` is guaranteed to occur if 10004 the following conditions are met: 10005 10006 - Caller and callee both have the calling convention ``fastcc``. 10007 - The call is in tail position (ret immediately follows call and ret 10008 uses value of call or is void). 10009 - Option ``-tailcallopt`` is enabled, or 10010 ``llvm::GuaranteedTailCallOpt`` is ``true``. 10011 - `Platform-specific constraints are 10012 met. <CodeGenerator.html#tailcallopt>`_ 10013 10014#. The optional ``notail`` marker indicates that the optimizers should not add 10015 ``tail`` or ``musttail`` markers to the call. It is used to prevent tail 10016 call optimization from being performed on the call. 10017 10018#. The optional ``fast-math flags`` marker indicates that the call has one or more 10019 :ref:`fast-math flags <fastmath>`, which are optimization hints to enable 10020 otherwise unsafe floating-point optimizations. Fast-math flags are only valid 10021 for calls that return a floating-point scalar or vector type. 10022 10023#. The optional "cconv" marker indicates which :ref:`calling 10024 convention <callingconv>` the call should use. If none is 10025 specified, the call defaults to using C calling conventions. The 10026 calling convention of the call must match the calling convention of 10027 the target function, or else the behavior is undefined. 10028#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 10029 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 10030 are valid here. 10031#. The optional addrspace attribute can be used to indicate the address space 10032 of the called function. If it is not specified, the program address space 10033 from the :ref:`datalayout string<langref_datalayout>` will be used. 10034#. '``ty``': the type of the call instruction itself which is also the 10035 type of the return value. Functions that return no value are marked 10036 ``void``. 10037#. '``fnty``': shall be the signature of the function being called. The 10038 argument types must match the types implied by this signature. This 10039 type can be omitted if the function is not varargs. 10040#. '``fnptrval``': An LLVM value containing a pointer to a function to 10041 be called. In most cases, this is a direct function call, but 10042 indirect ``call``'s are just as possible, calling an arbitrary pointer 10043 to function value. 10044#. '``function args``': argument list whose types match the function 10045 signature argument types and parameter attributes. All arguments must 10046 be of :ref:`first class <t_firstclass>` type. If the function signature 10047 indicates the function accepts a variable number of arguments, the 10048 extra arguments can be specified. 10049#. The optional :ref:`function attributes <fnattrs>` list. 10050#. The optional :ref:`operand bundles <opbundles>` list. 10051 10052Semantics: 10053"""""""""" 10054 10055The '``call``' instruction is used to cause control flow to transfer to 10056a specified function, with its incoming arguments bound to the specified 10057values. Upon a '``ret``' instruction in the called function, control 10058flow continues with the instruction after the function call, and the 10059return value of the function is bound to the result argument. 10060 10061Example: 10062"""""""" 10063 10064.. code-block:: llvm 10065 10066 %retval = call i32 @test(i32 %argc) 10067 call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) ; yields i32 10068 %X = tail call i32 @foo() ; yields i32 10069 %Y = tail call fastcc i32 @foo() ; yields i32 10070 call void %foo(i8 97 signext) 10071 10072 %struct.A = type { i32, i8 } 10073 %r = call %struct.A @foo() ; yields { i32, i8 } 10074 %gr = extractvalue %struct.A %r, 0 ; yields i32 10075 %gr1 = extractvalue %struct.A %r, 1 ; yields i8 10076 %Z = call void @foo() noreturn ; indicates that %foo never returns normally 10077 %ZZ = call zeroext i32 @bar() ; Return value is %zero extended 10078 10079llvm treats calls to some functions with names and arguments that match 10080the standard C99 library as being the C99 library functions, and may 10081perform optimizations or generate code for them under that assumption. 10082This is something we'd like to change in the future to provide better 10083support for freestanding environments and non-C-based languages. 10084 10085.. _i_va_arg: 10086 10087'``va_arg``' Instruction 10088^^^^^^^^^^^^^^^^^^^^^^^^ 10089 10090Syntax: 10091""""""" 10092 10093:: 10094 10095 <resultval> = va_arg <va_list*> <arglist>, <argty> 10096 10097Overview: 10098""""""""" 10099 10100The '``va_arg``' instruction is used to access arguments passed through 10101the "variable argument" area of a function call. It is used to implement 10102the ``va_arg`` macro in C. 10103 10104Arguments: 10105"""""""""" 10106 10107This instruction takes a ``va_list*`` value and the type of the 10108argument. It returns a value of the specified argument type and 10109increments the ``va_list`` to point to the next argument. The actual 10110type of ``va_list`` is target specific. 10111 10112Semantics: 10113"""""""""" 10114 10115The '``va_arg``' instruction loads an argument of the specified type 10116from the specified ``va_list`` and causes the ``va_list`` to point to 10117the next argument. For more information, see the variable argument 10118handling :ref:`Intrinsic Functions <int_varargs>`. 10119 10120It is legal for this instruction to be called in a function which does 10121not take a variable number of arguments, for example, the ``vfprintf`` 10122function. 10123 10124``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic 10125function <intrinsics>` because it takes a type as an argument. 10126 10127Example: 10128"""""""" 10129 10130See the :ref:`variable argument processing <int_varargs>` section. 10131 10132Note that the code generator does not yet fully support va\_arg on many 10133targets. Also, it does not currently support va\_arg with aggregate 10134types on any target. 10135 10136.. _i_landingpad: 10137 10138'``landingpad``' Instruction 10139^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10140 10141Syntax: 10142""""""" 10143 10144:: 10145 10146 <resultval> = landingpad <resultty> <clause>+ 10147 <resultval> = landingpad <resultty> cleanup <clause>* 10148 10149 <clause> := catch <type> <value> 10150 <clause> := filter <array constant type> <array constant> 10151 10152Overview: 10153""""""""" 10154 10155The '``landingpad``' instruction is used by `LLVM's exception handling 10156system <ExceptionHandling.html#overview>`_ to specify that a basic block 10157is a landing pad --- one where the exception lands, and corresponds to the 10158code found in the ``catch`` portion of a ``try``/``catch`` sequence. It 10159defines values supplied by the :ref:`personality function <personalityfn>` upon 10160re-entry to the function. The ``resultval`` has the type ``resultty``. 10161 10162Arguments: 10163"""""""""" 10164 10165The optional 10166``cleanup`` flag indicates that the landing pad block is a cleanup. 10167 10168A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and 10169contains the global variable representing the "type" that may be caught 10170or filtered respectively. Unlike the ``catch`` clause, the ``filter`` 10171clause takes an array constant as its argument. Use 10172"``[0 x i8**] undef``" for a filter which cannot throw. The 10173'``landingpad``' instruction must contain *at least* one ``clause`` or 10174the ``cleanup`` flag. 10175 10176Semantics: 10177"""""""""" 10178 10179The '``landingpad``' instruction defines the values which are set by the 10180:ref:`personality function <personalityfn>` upon re-entry to the function, and 10181therefore the "result type" of the ``landingpad`` instruction. As with 10182calling conventions, how the personality function results are 10183represented in LLVM IR is target specific. 10184 10185The clauses are applied in order from top to bottom. If two 10186``landingpad`` instructions are merged together through inlining, the 10187clauses from the calling function are appended to the list of clauses. 10188When the call stack is being unwound due to an exception being thrown, 10189the exception is compared against each ``clause`` in turn. If it doesn't 10190match any of the clauses, and the ``cleanup`` flag is not set, then 10191unwinding continues further up the call stack. 10192 10193The ``landingpad`` instruction has several restrictions: 10194 10195- A landing pad block is a basic block which is the unwind destination 10196 of an '``invoke``' instruction. 10197- A landing pad block must have a '``landingpad``' instruction as its 10198 first non-PHI instruction. 10199- There can be only one '``landingpad``' instruction within the landing 10200 pad block. 10201- A basic block that is not a landing pad block may not include a 10202 '``landingpad``' instruction. 10203 10204Example: 10205"""""""" 10206 10207.. code-block:: llvm 10208 10209 ;; A landing pad which can catch an integer. 10210 %res = landingpad { i8*, i32 } 10211 catch i8** @_ZTIi 10212 ;; A landing pad that is a cleanup. 10213 %res = landingpad { i8*, i32 } 10214 cleanup 10215 ;; A landing pad which can catch an integer and can only throw a double. 10216 %res = landingpad { i8*, i32 } 10217 catch i8** @_ZTIi 10218 filter [1 x i8**] [@_ZTId] 10219 10220.. _i_catchpad: 10221 10222'``catchpad``' Instruction 10223^^^^^^^^^^^^^^^^^^^^^^^^^^ 10224 10225Syntax: 10226""""""" 10227 10228:: 10229 10230 <resultval> = catchpad within <catchswitch> [<args>*] 10231 10232Overview: 10233""""""""" 10234 10235The '``catchpad``' instruction is used by `LLVM's exception handling 10236system <ExceptionHandling.html#overview>`_ to specify that a basic block 10237begins a catch handler --- one where a personality routine attempts to transfer 10238control to catch an exception. 10239 10240Arguments: 10241"""""""""" 10242 10243The ``catchswitch`` operand must always be a token produced by a 10244:ref:`catchswitch <i_catchswitch>` instruction in a predecessor block. This 10245ensures that each ``catchpad`` has exactly one predecessor block, and it always 10246terminates in a ``catchswitch``. 10247 10248The ``args`` correspond to whatever information the personality routine 10249requires to know if this is an appropriate handler for the exception. Control 10250will transfer to the ``catchpad`` if this is the first appropriate handler for 10251the exception. 10252 10253The ``resultval`` has the type :ref:`token <t_token>` and is used to match the 10254``catchpad`` to corresponding :ref:`catchrets <i_catchret>` and other nested EH 10255pads. 10256 10257Semantics: 10258"""""""""" 10259 10260When the call stack is being unwound due to an exception being thrown, the 10261exception is compared against the ``args``. If it doesn't match, control will 10262not reach the ``catchpad`` instruction. The representation of ``args`` is 10263entirely target and personality function-specific. 10264 10265Like the :ref:`landingpad <i_landingpad>` instruction, the ``catchpad`` 10266instruction must be the first non-phi of its parent basic block. 10267 10268The meaning of the tokens produced and consumed by ``catchpad`` and other "pad" 10269instructions is described in the 10270`Windows exception handling documentation\ <ExceptionHandling.html#wineh>`_. 10271 10272When a ``catchpad`` has been "entered" but not yet "exited" (as 10273described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 10274it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 10275that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`. 10276 10277Example: 10278"""""""" 10279 10280.. code-block:: text 10281 10282 dispatch: 10283 %cs = catchswitch within none [label %handler0] unwind to caller 10284 ;; A catch block which can catch an integer. 10285 handler0: 10286 %tok = catchpad within %cs [i8** @_ZTIi] 10287 10288.. _i_cleanuppad: 10289 10290'``cleanuppad``' Instruction 10291^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10292 10293Syntax: 10294""""""" 10295 10296:: 10297 10298 <resultval> = cleanuppad within <parent> [<args>*] 10299 10300Overview: 10301""""""""" 10302 10303The '``cleanuppad``' instruction is used by `LLVM's exception handling 10304system <ExceptionHandling.html#overview>`_ to specify that a basic block 10305is a cleanup block --- one where a personality routine attempts to 10306transfer control to run cleanup actions. 10307The ``args`` correspond to whatever additional 10308information the :ref:`personality function <personalityfn>` requires to 10309execute the cleanup. 10310The ``resultval`` has the type :ref:`token <t_token>` and is used to 10311match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`. 10312The ``parent`` argument is the token of the funclet that contains the 10313``cleanuppad`` instruction. If the ``cleanuppad`` is not inside a funclet, 10314this operand may be the token ``none``. 10315 10316Arguments: 10317"""""""""" 10318 10319The instruction takes a list of arbitrary values which are interpreted 10320by the :ref:`personality function <personalityfn>`. 10321 10322Semantics: 10323"""""""""" 10324 10325When the call stack is being unwound due to an exception being thrown, 10326the :ref:`personality function <personalityfn>` transfers control to the 10327``cleanuppad`` with the aid of the personality-specific arguments. 10328As with calling conventions, how the personality function results are 10329represented in LLVM IR is target specific. 10330 10331The ``cleanuppad`` instruction has several restrictions: 10332 10333- A cleanup block is a basic block which is the unwind destination of 10334 an exceptional instruction. 10335- A cleanup block must have a '``cleanuppad``' instruction as its 10336 first non-PHI instruction. 10337- There can be only one '``cleanuppad``' instruction within the 10338 cleanup block. 10339- A basic block that is not a cleanup block may not include a 10340 '``cleanuppad``' instruction. 10341 10342When a ``cleanuppad`` has been "entered" but not yet "exited" (as 10343described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 10344it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 10345that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`. 10346 10347Example: 10348"""""""" 10349 10350.. code-block:: text 10351 10352 %tok = cleanuppad within %cs [] 10353 10354.. _intrinsics: 10355 10356Intrinsic Functions 10357=================== 10358 10359LLVM supports the notion of an "intrinsic function". These functions 10360have well known names and semantics and are required to follow certain 10361restrictions. Overall, these intrinsics represent an extension mechanism 10362for the LLVM language that does not require changing all of the 10363transformations in LLVM when adding to the language (or the bitcode 10364reader/writer, the parser, etc...). 10365 10366Intrinsic function names must all start with an "``llvm.``" prefix. This 10367prefix is reserved in LLVM for intrinsic names; thus, function names may 10368not begin with this prefix. Intrinsic functions must always be external 10369functions: you cannot define the body of intrinsic functions. Intrinsic 10370functions may only be used in call or invoke instructions: it is illegal 10371to take the address of an intrinsic function. Additionally, because 10372intrinsic functions are part of the LLVM language, it is required if any 10373are added that they be documented here. 10374 10375Some intrinsic functions can be overloaded, i.e., the intrinsic 10376represents a family of functions that perform the same operation but on 10377different data types. Because LLVM can represent over 8 million 10378different integer types, overloading is used commonly to allow an 10379intrinsic function to operate on any integer type. One or more of the 10380argument types or the result type can be overloaded to accept any 10381integer type. Argument types may also be defined as exactly matching a 10382previous argument's type or the result type. This allows an intrinsic 10383function which accepts multiple arguments, but needs all of them to be 10384of the same type, to only be overloaded with respect to a single 10385argument or the result. 10386 10387Overloaded intrinsics will have the names of its overloaded argument 10388types encoded into its function name, each preceded by a period. Only 10389those types which are overloaded result in a name suffix. Arguments 10390whose type is matched against another type do not. For example, the 10391``llvm.ctpop`` function can take an integer of any width and returns an 10392integer of exactly the same integer width. This leads to a family of 10393functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and 10394``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is 10395overloaded, and only one type suffix is required. Because the argument's 10396type is matched against the return type, it does not require its own 10397name suffix. 10398 10399To learn how to add an intrinsic function, please see the `Extending 10400LLVM Guide <ExtendingLLVM.html>`_. 10401 10402.. _int_varargs: 10403 10404Variable Argument Handling Intrinsics 10405------------------------------------- 10406 10407Variable argument support is defined in LLVM with the 10408:ref:`va_arg <i_va_arg>` instruction and these three intrinsic 10409functions. These functions are related to the similarly named macros 10410defined in the ``<stdarg.h>`` header file. 10411 10412All of these functions operate on arguments that use a target-specific 10413value type "``va_list``". The LLVM assembly language reference manual 10414does not define what this type is, so all transformations should be 10415prepared to handle these functions regardless of the type used. 10416 10417This example shows how the :ref:`va_arg <i_va_arg>` instruction and the 10418variable argument handling intrinsic functions are used. 10419 10420.. code-block:: llvm 10421 10422 ; This struct is different for every platform. For most platforms, 10423 ; it is merely an i8*. 10424 %struct.va_list = type { i8* } 10425 10426 ; For Unix x86_64 platforms, va_list is the following struct: 10427 ; %struct.va_list = type { i32, i32, i8*, i8* } 10428 10429 define i32 @test(i32 %X, ...) { 10430 ; Initialize variable argument processing 10431 %ap = alloca %struct.va_list 10432 %ap2 = bitcast %struct.va_list* %ap to i8* 10433 call void @llvm.va_start(i8* %ap2) 10434 10435 ; Read a single integer argument 10436 %tmp = va_arg i8* %ap2, i32 10437 10438 ; Demonstrate usage of llvm.va_copy and llvm.va_end 10439 %aq = alloca i8* 10440 %aq2 = bitcast i8** %aq to i8* 10441 call void @llvm.va_copy(i8* %aq2, i8* %ap2) 10442 call void @llvm.va_end(i8* %aq2) 10443 10444 ; Stop processing of arguments. 10445 call void @llvm.va_end(i8* %ap2) 10446 ret i32 %tmp 10447 } 10448 10449 declare void @llvm.va_start(i8*) 10450 declare void @llvm.va_copy(i8*, i8*) 10451 declare void @llvm.va_end(i8*) 10452 10453.. _int_va_start: 10454 10455'``llvm.va_start``' Intrinsic 10456^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10457 10458Syntax: 10459""""""" 10460 10461:: 10462 10463 declare void @llvm.va_start(i8* <arglist>) 10464 10465Overview: 10466""""""""" 10467 10468The '``llvm.va_start``' intrinsic initializes ``*<arglist>`` for 10469subsequent use by ``va_arg``. 10470 10471Arguments: 10472"""""""""" 10473 10474The argument is a pointer to a ``va_list`` element to initialize. 10475 10476Semantics: 10477"""""""""" 10478 10479The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro 10480available in C. In a target-dependent way, it initializes the 10481``va_list`` element to which the argument points, so that the next call 10482to ``va_arg`` will produce the first variable argument passed to the 10483function. Unlike the C ``va_start`` macro, this intrinsic does not need 10484to know the last argument of the function as the compiler can figure 10485that out. 10486 10487'``llvm.va_end``' Intrinsic 10488^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10489 10490Syntax: 10491""""""" 10492 10493:: 10494 10495 declare void @llvm.va_end(i8* <arglist>) 10496 10497Overview: 10498""""""""" 10499 10500The '``llvm.va_end``' intrinsic destroys ``*<arglist>``, which has been 10501initialized previously with ``llvm.va_start`` or ``llvm.va_copy``. 10502 10503Arguments: 10504"""""""""" 10505 10506The argument is a pointer to a ``va_list`` to destroy. 10507 10508Semantics: 10509"""""""""" 10510 10511The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro 10512available in C. In a target-dependent way, it destroys the ``va_list`` 10513element to which the argument points. Calls to 10514:ref:`llvm.va_start <int_va_start>` and 10515:ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to 10516``llvm.va_end``. 10517 10518.. _int_va_copy: 10519 10520'``llvm.va_copy``' Intrinsic 10521^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10522 10523Syntax: 10524""""""" 10525 10526:: 10527 10528 declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>) 10529 10530Overview: 10531""""""""" 10532 10533The '``llvm.va_copy``' intrinsic copies the current argument position 10534from the source argument list to the destination argument list. 10535 10536Arguments: 10537"""""""""" 10538 10539The first argument is a pointer to a ``va_list`` element to initialize. 10540The second argument is a pointer to a ``va_list`` element to copy from. 10541 10542Semantics: 10543"""""""""" 10544 10545The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro 10546available in C. In a target-dependent way, it copies the source 10547``va_list`` element into the destination ``va_list`` element. This 10548intrinsic is necessary because the `` llvm.va_start`` intrinsic may be 10549arbitrarily complex and require, for example, memory allocation. 10550 10551Accurate Garbage Collection Intrinsics 10552-------------------------------------- 10553 10554LLVM's support for `Accurate Garbage Collection <GarbageCollection.html>`_ 10555(GC) requires the frontend to generate code containing appropriate intrinsic 10556calls and select an appropriate GC strategy which knows how to lower these 10557intrinsics in a manner which is appropriate for the target collector. 10558 10559These intrinsics allow identification of :ref:`GC roots on the 10560stack <int_gcroot>`, as well as garbage collector implementations that 10561require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. 10562Frontends for type-safe garbage collected languages should generate 10563these intrinsics to make use of the LLVM garbage collectors. For more 10564details, see `Garbage Collection with LLVM <GarbageCollection.html>`_. 10565 10566Experimental Statepoint Intrinsics 10567^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10568 10569LLVM provides an second experimental set of intrinsics for describing garbage 10570collection safepoints in compiled code. These intrinsics are an alternative 10571to the ``llvm.gcroot`` intrinsics, but are compatible with the ones for 10572:ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. The 10573differences in approach are covered in the `Garbage Collection with LLVM 10574<GarbageCollection.html>`_ documentation. The intrinsics themselves are 10575described in :doc:`Statepoints`. 10576 10577.. _int_gcroot: 10578 10579'``llvm.gcroot``' Intrinsic 10580^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10581 10582Syntax: 10583""""""" 10584 10585:: 10586 10587 declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata) 10588 10589Overview: 10590""""""""" 10591 10592The '``llvm.gcroot``' intrinsic declares the existence of a GC root to 10593the code generator, and allows some metadata to be associated with it. 10594 10595Arguments: 10596"""""""""" 10597 10598The first argument specifies the address of a stack object that contains 10599the root pointer. The second pointer (which must be either a constant or 10600a global value address) contains the meta-data to be associated with the 10601root. 10602 10603Semantics: 10604"""""""""" 10605 10606At runtime, a call to this intrinsic stores a null pointer into the 10607"ptrloc" location. At compile-time, the code generator generates 10608information to allow the runtime to find the pointer at GC safe points. 10609The '``llvm.gcroot``' intrinsic may only be used in a function which 10610:ref:`specifies a GC algorithm <gc>`. 10611 10612.. _int_gcread: 10613 10614'``llvm.gcread``' Intrinsic 10615^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10616 10617Syntax: 10618""""""" 10619 10620:: 10621 10622 declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr) 10623 10624Overview: 10625""""""""" 10626 10627The '``llvm.gcread``' intrinsic identifies reads of references from heap 10628locations, allowing garbage collector implementations that require read 10629barriers. 10630 10631Arguments: 10632"""""""""" 10633 10634The second argument is the address to read from, which should be an 10635address allocated from the garbage collector. The first object is a 10636pointer to the start of the referenced object, if needed by the language 10637runtime (otherwise null). 10638 10639Semantics: 10640"""""""""" 10641 10642The '``llvm.gcread``' intrinsic has the same semantics as a load 10643instruction, but may be replaced with substantially more complex code by 10644the garbage collector runtime, as needed. The '``llvm.gcread``' 10645intrinsic may only be used in a function which :ref:`specifies a GC 10646algorithm <gc>`. 10647 10648.. _int_gcwrite: 10649 10650'``llvm.gcwrite``' Intrinsic 10651^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10652 10653Syntax: 10654""""""" 10655 10656:: 10657 10658 declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2) 10659 10660Overview: 10661""""""""" 10662 10663The '``llvm.gcwrite``' intrinsic identifies writes of references to heap 10664locations, allowing garbage collector implementations that require write 10665barriers (such as generational or reference counting collectors). 10666 10667Arguments: 10668"""""""""" 10669 10670The first argument is the reference to store, the second is the start of 10671the object to store it to, and the third is the address of the field of 10672Obj to store to. If the runtime does not require a pointer to the 10673object, Obj may be null. 10674 10675Semantics: 10676"""""""""" 10677 10678The '``llvm.gcwrite``' intrinsic has the same semantics as a store 10679instruction, but may be replaced with substantially more complex code by 10680the garbage collector runtime, as needed. The '``llvm.gcwrite``' 10681intrinsic may only be used in a function which :ref:`specifies a GC 10682algorithm <gc>`. 10683 10684Code Generator Intrinsics 10685------------------------- 10686 10687These intrinsics are provided by LLVM to expose special features that 10688may only be implemented with code generator support. 10689 10690'``llvm.returnaddress``' Intrinsic 10691^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10692 10693Syntax: 10694""""""" 10695 10696:: 10697 10698 declare i8* @llvm.returnaddress(i32 <level>) 10699 10700Overview: 10701""""""""" 10702 10703The '``llvm.returnaddress``' intrinsic attempts to compute a 10704target-specific value indicating the return address of the current 10705function or one of its callers. 10706 10707Arguments: 10708"""""""""" 10709 10710The argument to this intrinsic indicates which function to return the 10711address for. Zero indicates the calling function, one indicates its 10712caller, etc. The argument is **required** to be a constant integer 10713value. 10714 10715Semantics: 10716"""""""""" 10717 10718The '``llvm.returnaddress``' intrinsic either returns a pointer 10719indicating the return address of the specified call frame, or zero if it 10720cannot be identified. The value returned by this intrinsic is likely to 10721be incorrect or 0 for arguments other than zero, so it should only be 10722used for debugging purposes. 10723 10724Note that calling this intrinsic does not prevent function inlining or 10725other aggressive transformations, so the value returned may not be that 10726of the obvious source-language caller. 10727 10728'``llvm.addressofreturnaddress``' Intrinsic 10729^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10730 10731Syntax: 10732""""""" 10733 10734:: 10735 10736 declare i8* @llvm.addressofreturnaddress() 10737 10738Overview: 10739""""""""" 10740 10741The '``llvm.addressofreturnaddress``' intrinsic returns a target-specific 10742pointer to the place in the stack frame where the return address of the 10743current function is stored. 10744 10745Semantics: 10746"""""""""" 10747 10748Note that calling this intrinsic does not prevent function inlining or 10749other aggressive transformations, so the value returned may not be that 10750of the obvious source-language caller. 10751 10752This intrinsic is only implemented for x86 and aarch64. 10753 10754'``llvm.sponentry``' Intrinsic 10755^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10756 10757Syntax: 10758""""""" 10759 10760:: 10761 10762 declare i8* @llvm.sponentry() 10763 10764Overview: 10765""""""""" 10766 10767The '``llvm.sponentry``' intrinsic returns the stack pointer value at 10768the entry of the current function calling this intrinsic. 10769 10770Semantics: 10771"""""""""" 10772 10773Note this intrinsic is only verified on AArch64. 10774 10775'``llvm.frameaddress``' Intrinsic 10776^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10777 10778Syntax: 10779""""""" 10780 10781:: 10782 10783 declare i8* @llvm.frameaddress(i32 <level>) 10784 10785Overview: 10786""""""""" 10787 10788The '``llvm.frameaddress``' intrinsic attempts to return the 10789target-specific frame pointer value for the specified stack frame. 10790 10791Arguments: 10792"""""""""" 10793 10794The argument to this intrinsic indicates which function to return the 10795frame pointer for. Zero indicates the calling function, one indicates 10796its caller, etc. The argument is **required** to be a constant integer 10797value. 10798 10799Semantics: 10800"""""""""" 10801 10802The '``llvm.frameaddress``' intrinsic either returns a pointer 10803indicating the frame address of the specified call frame, or zero if it 10804cannot be identified. The value returned by this intrinsic is likely to 10805be incorrect or 0 for arguments other than zero, so it should only be 10806used for debugging purposes. 10807 10808Note that calling this intrinsic does not prevent function inlining or 10809other aggressive transformations, so the value returned may not be that 10810of the obvious source-language caller. 10811 10812'``llvm.localescape``' and '``llvm.localrecover``' Intrinsics 10813^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10814 10815Syntax: 10816""""""" 10817 10818:: 10819 10820 declare void @llvm.localescape(...) 10821 declare i8* @llvm.localrecover(i8* %func, i8* %fp, i32 %idx) 10822 10823Overview: 10824""""""""" 10825 10826The '``llvm.localescape``' intrinsic escapes offsets of a collection of static 10827allocas, and the '``llvm.localrecover``' intrinsic applies those offsets to a 10828live frame pointer to recover the address of the allocation. The offset is 10829computed during frame layout of the caller of ``llvm.localescape``. 10830 10831Arguments: 10832"""""""""" 10833 10834All arguments to '``llvm.localescape``' must be pointers to static allocas or 10835casts of static allocas. Each function can only call '``llvm.localescape``' 10836once, and it can only do so from the entry block. 10837 10838The ``func`` argument to '``llvm.localrecover``' must be a constant 10839bitcasted pointer to a function defined in the current module. The code 10840generator cannot determine the frame allocation offset of functions defined in 10841other modules. 10842 10843The ``fp`` argument to '``llvm.localrecover``' must be a frame pointer of a 10844call frame that is currently live. The return value of '``llvm.localaddress``' 10845is one way to produce such a value, but various runtimes also expose a suitable 10846pointer in platform-specific ways. 10847 10848The ``idx`` argument to '``llvm.localrecover``' indicates which alloca passed to 10849'``llvm.localescape``' to recover. It is zero-indexed. 10850 10851Semantics: 10852"""""""""" 10853 10854These intrinsics allow a group of functions to share access to a set of local 10855stack allocations of a one parent function. The parent function may call the 10856'``llvm.localescape``' intrinsic once from the function entry block, and the 10857child functions can use '``llvm.localrecover``' to access the escaped allocas. 10858The '``llvm.localescape``' intrinsic blocks inlining, as inlining changes where 10859the escaped allocas are allocated, which would break attempts to use 10860'``llvm.localrecover``'. 10861 10862.. _int_read_register: 10863.. _int_write_register: 10864 10865'``llvm.read_register``' and '``llvm.write_register``' Intrinsics 10866^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10867 10868Syntax: 10869""""""" 10870 10871:: 10872 10873 declare i32 @llvm.read_register.i32(metadata) 10874 declare i64 @llvm.read_register.i64(metadata) 10875 declare void @llvm.write_register.i32(metadata, i32 @value) 10876 declare void @llvm.write_register.i64(metadata, i64 @value) 10877 !0 = !{!"sp\00"} 10878 10879Overview: 10880""""""""" 10881 10882The '``llvm.read_register``' and '``llvm.write_register``' intrinsics 10883provides access to the named register. The register must be valid on 10884the architecture being compiled to. The type needs to be compatible 10885with the register being read. 10886 10887Semantics: 10888"""""""""" 10889 10890The '``llvm.read_register``' intrinsic returns the current value of the 10891register, where possible. The '``llvm.write_register``' intrinsic sets 10892the current value of the register, where possible. 10893 10894This is useful to implement named register global variables that need 10895to always be mapped to a specific register, as is common practice on 10896bare-metal programs including OS kernels. 10897 10898The compiler doesn't check for register availability or use of the used 10899register in surrounding code, including inline assembly. Because of that, 10900allocatable registers are not supported. 10901 10902Warning: So far it only works with the stack pointer on selected 10903architectures (ARM, AArch64, PowerPC and x86_64). Significant amount of 10904work is needed to support other registers and even more so, allocatable 10905registers. 10906 10907.. _int_stacksave: 10908 10909'``llvm.stacksave``' Intrinsic 10910^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10911 10912Syntax: 10913""""""" 10914 10915:: 10916 10917 declare i8* @llvm.stacksave() 10918 10919Overview: 10920""""""""" 10921 10922The '``llvm.stacksave``' intrinsic is used to remember the current state 10923of the function stack, for use with 10924:ref:`llvm.stackrestore <int_stackrestore>`. This is useful for 10925implementing language features like scoped automatic variable sized 10926arrays in C99. 10927 10928Semantics: 10929"""""""""" 10930 10931This intrinsic returns a opaque pointer value that can be passed to 10932:ref:`llvm.stackrestore <int_stackrestore>`. When an 10933``llvm.stackrestore`` intrinsic is executed with a value saved from 10934``llvm.stacksave``, it effectively restores the state of the stack to 10935the state it was in when the ``llvm.stacksave`` intrinsic executed. In 10936practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that 10937were allocated after the ``llvm.stacksave`` was executed. 10938 10939.. _int_stackrestore: 10940 10941'``llvm.stackrestore``' Intrinsic 10942^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10943 10944Syntax: 10945""""""" 10946 10947:: 10948 10949 declare void @llvm.stackrestore(i8* %ptr) 10950 10951Overview: 10952""""""""" 10953 10954The '``llvm.stackrestore``' intrinsic is used to restore the state of 10955the function stack to the state it was in when the corresponding 10956:ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is 10957useful for implementing language features like scoped automatic variable 10958sized arrays in C99. 10959 10960Semantics: 10961"""""""""" 10962 10963See the description for :ref:`llvm.stacksave <int_stacksave>`. 10964 10965.. _int_get_dynamic_area_offset: 10966 10967'``llvm.get.dynamic.area.offset``' Intrinsic 10968^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10969 10970Syntax: 10971""""""" 10972 10973:: 10974 10975 declare i32 @llvm.get.dynamic.area.offset.i32() 10976 declare i64 @llvm.get.dynamic.area.offset.i64() 10977 10978Overview: 10979""""""""" 10980 10981 The '``llvm.get.dynamic.area.offset.*``' intrinsic family is used to 10982 get the offset from native stack pointer to the address of the most 10983 recent dynamic alloca on the caller's stack. These intrinsics are 10984 intendend for use in combination with 10985 :ref:`llvm.stacksave <int_stacksave>` to get a 10986 pointer to the most recent dynamic alloca. This is useful, for example, 10987 for AddressSanitizer's stack unpoisoning routines. 10988 10989Semantics: 10990"""""""""" 10991 10992 These intrinsics return a non-negative integer value that can be used to 10993 get the address of the most recent dynamic alloca, allocated by :ref:`alloca <i_alloca>` 10994 on the caller's stack. In particular, for targets where stack grows downwards, 10995 adding this offset to the native stack pointer would get the address of the most 10996 recent dynamic alloca. For targets where stack grows upwards, the situation is a bit more 10997 complicated, because subtracting this value from stack pointer would get the address 10998 one past the end of the most recent dynamic alloca. 10999 11000 Although for most targets `llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>` 11001 returns just a zero, for others, such as PowerPC and PowerPC64, it returns a 11002 compile-time-known constant value. 11003 11004 The return value type of :ref:`llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>` 11005 must match the target's default address space's (address space 0) pointer type. 11006 11007'``llvm.prefetch``' Intrinsic 11008^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11009 11010Syntax: 11011""""""" 11012 11013:: 11014 11015 declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>) 11016 11017Overview: 11018""""""""" 11019 11020The '``llvm.prefetch``' intrinsic is a hint to the code generator to 11021insert a prefetch instruction if supported; otherwise, it is a noop. 11022Prefetches have no effect on the behavior of the program but can change 11023its performance characteristics. 11024 11025Arguments: 11026"""""""""" 11027 11028``address`` is the address to be prefetched, ``rw`` is the specifier 11029determining if the fetch should be for a read (0) or write (1), and 11030``locality`` is a temporal locality specifier ranging from (0) - no 11031locality, to (3) - extremely local keep in cache. The ``cache type`` 11032specifies whether the prefetch is performed on the data (1) or 11033instruction (0) cache. The ``rw``, ``locality`` and ``cache type`` 11034arguments must be constant integers. 11035 11036Semantics: 11037"""""""""" 11038 11039This intrinsic does not modify the behavior of the program. In 11040particular, prefetches cannot trap and do not produce a value. On 11041targets that support this intrinsic, the prefetch can provide hints to 11042the processor cache for better performance. 11043 11044'``llvm.pcmarker``' Intrinsic 11045^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11046 11047Syntax: 11048""""""" 11049 11050:: 11051 11052 declare void @llvm.pcmarker(i32 <id>) 11053 11054Overview: 11055""""""""" 11056 11057The '``llvm.pcmarker``' intrinsic is a method to export a Program 11058Counter (PC) in a region of code to simulators and other tools. The 11059method is target specific, but it is expected that the marker will use 11060exported symbols to transmit the PC of the marker. The marker makes no 11061guarantees that it will remain with any specific instruction after 11062optimizations. It is possible that the presence of a marker will inhibit 11063optimizations. The intended use is to be inserted after optimizations to 11064allow correlations of simulation runs. 11065 11066Arguments: 11067"""""""""" 11068 11069``id`` is a numerical id identifying the marker. 11070 11071Semantics: 11072"""""""""" 11073 11074This intrinsic does not modify the behavior of the program. Backends 11075that do not support this intrinsic may ignore it. 11076 11077'``llvm.readcyclecounter``' Intrinsic 11078^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11079 11080Syntax: 11081""""""" 11082 11083:: 11084 11085 declare i64 @llvm.readcyclecounter() 11086 11087Overview: 11088""""""""" 11089 11090The '``llvm.readcyclecounter``' intrinsic provides access to the cycle 11091counter register (or similar low latency, high accuracy clocks) on those 11092targets that support it. On X86, it should map to RDTSC. On Alpha, it 11093should map to RPCC. As the backing counters overflow quickly (on the 11094order of 9 seconds on alpha), this should only be used for small 11095timings. 11096 11097Semantics: 11098"""""""""" 11099 11100When directly supported, reading the cycle counter should not modify any 11101memory. Implementations are allowed to either return a application 11102specific value or a system wide value. On backends without support, this 11103is lowered to a constant 0. 11104 11105Note that runtime support may be conditional on the privilege-level code is 11106running at and the host platform. 11107 11108'``llvm.clear_cache``' Intrinsic 11109^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11110 11111Syntax: 11112""""""" 11113 11114:: 11115 11116 declare void @llvm.clear_cache(i8*, i8*) 11117 11118Overview: 11119""""""""" 11120 11121The '``llvm.clear_cache``' intrinsic ensures visibility of modifications 11122in the specified range to the execution unit of the processor. On 11123targets with non-unified instruction and data cache, the implementation 11124flushes the instruction cache. 11125 11126Semantics: 11127"""""""""" 11128 11129On platforms with coherent instruction and data caches (e.g. x86), this 11130intrinsic is a nop. On platforms with non-coherent instruction and data 11131cache (e.g. ARM, MIPS), the intrinsic is lowered either to appropriate 11132instructions or a system call, if cache flushing requires special 11133privileges. 11134 11135The default behavior is to emit a call to ``__clear_cache`` from the run 11136time library. 11137 11138This instrinsic does *not* empty the instruction pipeline. Modifications 11139of the current function are outside the scope of the intrinsic. 11140 11141'``llvm.instrprof.increment``' Intrinsic 11142^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11143 11144Syntax: 11145""""""" 11146 11147:: 11148 11149 declare void @llvm.instrprof.increment(i8* <name>, i64 <hash>, 11150 i32 <num-counters>, i32 <index>) 11151 11152Overview: 11153""""""""" 11154 11155The '``llvm.instrprof.increment``' intrinsic can be emitted by a 11156frontend for use with instrumentation based profiling. These will be 11157lowered by the ``-instrprof`` pass to generate execution counts of a 11158program at runtime. 11159 11160Arguments: 11161"""""""""" 11162 11163The first argument is a pointer to a global variable containing the 11164name of the entity being instrumented. This should generally be the 11165(mangled) function name for a set of counters. 11166 11167The second argument is a hash value that can be used by the consumer 11168of the profile data to detect changes to the instrumented source, and 11169the third is the number of counters associated with ``name``. It is an 11170error if ``hash`` or ``num-counters`` differ between two instances of 11171``instrprof.increment`` that refer to the same name. 11172 11173The last argument refers to which of the counters for ``name`` should 11174be incremented. It should be a value between 0 and ``num-counters``. 11175 11176Semantics: 11177"""""""""" 11178 11179This intrinsic represents an increment of a profiling counter. It will 11180cause the ``-instrprof`` pass to generate the appropriate data 11181structures and the code to increment the appropriate value, in a 11182format that can be written out by a compiler runtime and consumed via 11183the ``llvm-profdata`` tool. 11184 11185'``llvm.instrprof.increment.step``' Intrinsic 11186^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11187 11188Syntax: 11189""""""" 11190 11191:: 11192 11193 declare void @llvm.instrprof.increment.step(i8* <name>, i64 <hash>, 11194 i32 <num-counters>, 11195 i32 <index>, i64 <step>) 11196 11197Overview: 11198""""""""" 11199 11200The '``llvm.instrprof.increment.step``' intrinsic is an extension to 11201the '``llvm.instrprof.increment``' intrinsic with an additional fifth 11202argument to specify the step of the increment. 11203 11204Arguments: 11205"""""""""" 11206The first four arguments are the same as '``llvm.instrprof.increment``' 11207intrinsic. 11208 11209The last argument specifies the value of the increment of the counter variable. 11210 11211Semantics: 11212"""""""""" 11213See description of '``llvm.instrprof.increment``' instrinsic. 11214 11215 11216'``llvm.instrprof.value.profile``' Intrinsic 11217^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11218 11219Syntax: 11220""""""" 11221 11222:: 11223 11224 declare void @llvm.instrprof.value.profile(i8* <name>, i64 <hash>, 11225 i64 <value>, i32 <value_kind>, 11226 i32 <index>) 11227 11228Overview: 11229""""""""" 11230 11231The '``llvm.instrprof.value.profile``' intrinsic can be emitted by a 11232frontend for use with instrumentation based profiling. This will be 11233lowered by the ``-instrprof`` pass to find out the target values, 11234instrumented expressions take in a program at runtime. 11235 11236Arguments: 11237"""""""""" 11238 11239The first argument is a pointer to a global variable containing the 11240name of the entity being instrumented. ``name`` should generally be the 11241(mangled) function name for a set of counters. 11242 11243The second argument is a hash value that can be used by the consumer 11244of the profile data to detect changes to the instrumented source. It 11245is an error if ``hash`` differs between two instances of 11246``llvm.instrprof.*`` that refer to the same name. 11247 11248The third argument is the value of the expression being profiled. The profiled 11249expression's value should be representable as an unsigned 64-bit value. The 11250fourth argument represents the kind of value profiling that is being done. The 11251supported value profiling kinds are enumerated through the 11252``InstrProfValueKind`` type declared in the 11253``<include/llvm/ProfileData/InstrProf.h>`` header file. The last argument is the 11254index of the instrumented expression within ``name``. It should be >= 0. 11255 11256Semantics: 11257"""""""""" 11258 11259This intrinsic represents the point where a call to a runtime routine 11260should be inserted for value profiling of target expressions. ``-instrprof`` 11261pass will generate the appropriate data structures and replace the 11262``llvm.instrprof.value.profile`` intrinsic with the call to the profile 11263runtime library with proper arguments. 11264 11265'``llvm.thread.pointer``' Intrinsic 11266^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11267 11268Syntax: 11269""""""" 11270 11271:: 11272 11273 declare i8* @llvm.thread.pointer() 11274 11275Overview: 11276""""""""" 11277 11278The '``llvm.thread.pointer``' intrinsic returns the value of the thread 11279pointer. 11280 11281Semantics: 11282"""""""""" 11283 11284The '``llvm.thread.pointer``' intrinsic returns a pointer to the TLS area 11285for the current thread. The exact semantics of this value are target 11286specific: it may point to the start of TLS area, to the end, or somewhere 11287in the middle. Depending on the target, this intrinsic may read a register, 11288call a helper function, read from an alternate memory space, or perform 11289other operations necessary to locate the TLS area. Not all targets support 11290this intrinsic. 11291 11292Standard C Library Intrinsics 11293----------------------------- 11294 11295LLVM provides intrinsics for a few important standard C library 11296functions. These intrinsics allow source-language front-ends to pass 11297information about the alignment of the pointer arguments to the code 11298generator, providing opportunity for more efficient code generation. 11299 11300.. _int_memcpy: 11301 11302'``llvm.memcpy``' Intrinsic 11303^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11304 11305Syntax: 11306""""""" 11307 11308This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any 11309integer bit width and for different address spaces. Not all targets 11310support all bit widths however. 11311 11312:: 11313 11314 declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>, 11315 i32 <len>, i1 <isvolatile>) 11316 declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>, 11317 i64 <len>, i1 <isvolatile>) 11318 11319Overview: 11320""""""""" 11321 11322The '``llvm.memcpy.*``' intrinsics copy a block of memory from the 11323source location to the destination location. 11324 11325Note that, unlike the standard libc function, the ``llvm.memcpy.*`` 11326intrinsics do not return a value, takes extra isvolatile 11327arguments and the pointers can be in specified address spaces. 11328 11329Arguments: 11330"""""""""" 11331 11332The first argument is a pointer to the destination, the second is a 11333pointer to the source. The third argument is an integer argument 11334specifying the number of bytes to copy, and the fourth is a 11335boolean indicating a volatile access. 11336 11337The :ref:`align <attr_align>` parameter attribute can be provided 11338for the first and second arguments. 11339 11340If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is 11341a :ref:`volatile operation <volatile>`. The detailed access behavior is not 11342very cleanly specified and it is unwise to depend on it. 11343 11344Semantics: 11345"""""""""" 11346 11347The '``llvm.memcpy.*``' intrinsics copy a block of memory from the 11348source location to the destination location, which are not allowed to 11349overlap. It copies "len" bytes of memory over. If the argument is known 11350to be aligned to some boundary, this can be specified as an attribute on 11351the argument. 11352 11353If "len" is 0, the pointers may be NULL or dangling. However, they must still 11354be appropriately aligned. 11355 11356.. _int_memmove: 11357 11358'``llvm.memmove``' Intrinsic 11359^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11360 11361Syntax: 11362""""""" 11363 11364This is an overloaded intrinsic. You can use llvm.memmove on any integer 11365bit width and for different address space. Not all targets support all 11366bit widths however. 11367 11368:: 11369 11370 declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>, 11371 i32 <len>, i1 <isvolatile>) 11372 declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>, 11373 i64 <len>, i1 <isvolatile>) 11374 11375Overview: 11376""""""""" 11377 11378The '``llvm.memmove.*``' intrinsics move a block of memory from the 11379source location to the destination location. It is similar to the 11380'``llvm.memcpy``' intrinsic but allows the two memory locations to 11381overlap. 11382 11383Note that, unlike the standard libc function, the ``llvm.memmove.*`` 11384intrinsics do not return a value, takes an extra isvolatile 11385argument and the pointers can be in specified address spaces. 11386 11387Arguments: 11388"""""""""" 11389 11390The first argument is a pointer to the destination, the second is a 11391pointer to the source. The third argument is an integer argument 11392specifying the number of bytes to copy, and the fourth is a 11393boolean indicating a volatile access. 11394 11395The :ref:`align <attr_align>` parameter attribute can be provided 11396for the first and second arguments. 11397 11398If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call 11399is a :ref:`volatile operation <volatile>`. The detailed access behavior is 11400not very cleanly specified and it is unwise to depend on it. 11401 11402Semantics: 11403"""""""""" 11404 11405The '``llvm.memmove.*``' intrinsics copy a block of memory from the 11406source location to the destination location, which may overlap. It 11407copies "len" bytes of memory over. If the argument is known to be 11408aligned to some boundary, this can be specified as an attribute on 11409the argument. 11410 11411If "len" is 0, the pointers may be NULL or dangling. However, they must still 11412be appropriately aligned. 11413 11414.. _int_memset: 11415 11416'``llvm.memset.*``' Intrinsics 11417^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11418 11419Syntax: 11420""""""" 11421 11422This is an overloaded intrinsic. You can use llvm.memset on any integer 11423bit width and for different address spaces. However, not all targets 11424support all bit widths. 11425 11426:: 11427 11428 declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>, 11429 i32 <len>, i1 <isvolatile>) 11430 declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>, 11431 i64 <len>, i1 <isvolatile>) 11432 11433Overview: 11434""""""""" 11435 11436The '``llvm.memset.*``' intrinsics fill a block of memory with a 11437particular byte value. 11438 11439Note that, unlike the standard libc function, the ``llvm.memset`` 11440intrinsic does not return a value and takes an extra volatile 11441argument. Also, the destination can be in an arbitrary address space. 11442 11443Arguments: 11444"""""""""" 11445 11446The first argument is a pointer to the destination to fill, the second 11447is the byte value with which to fill it, the third argument is an 11448integer argument specifying the number of bytes to fill, and the fourth 11449is a boolean indicating a volatile access. 11450 11451The :ref:`align <attr_align>` parameter attribute can be provided 11452for the first arguments. 11453 11454If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is 11455a :ref:`volatile operation <volatile>`. The detailed access behavior is not 11456very cleanly specified and it is unwise to depend on it. 11457 11458Semantics: 11459"""""""""" 11460 11461The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting 11462at the destination location. If the argument is known to be 11463aligned to some boundary, this can be specified as an attribute on 11464the argument. 11465 11466If "len" is 0, the pointers may be NULL or dangling. However, they must still 11467be appropriately aligned. 11468 11469'``llvm.sqrt.*``' Intrinsic 11470^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11471 11472Syntax: 11473""""""" 11474 11475This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any 11476floating-point or vector of floating-point type. Not all targets support 11477all types however. 11478 11479:: 11480 11481 declare float @llvm.sqrt.f32(float %Val) 11482 declare double @llvm.sqrt.f64(double %Val) 11483 declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val) 11484 declare fp128 @llvm.sqrt.f128(fp128 %Val) 11485 declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val) 11486 11487Overview: 11488""""""""" 11489 11490The '``llvm.sqrt``' intrinsics return the square root of the specified value. 11491 11492Arguments: 11493"""""""""" 11494 11495The argument and return value are floating-point numbers of the same type. 11496 11497Semantics: 11498"""""""""" 11499 11500Return the same value as a corresponding libm '``sqrt``' function but without 11501trapping or setting ``errno``. For types specified by IEEE-754, the result 11502matches a conforming libm implementation. 11503 11504When specified with the fast-math-flag 'afn', the result may be approximated 11505using a less accurate calculation. 11506 11507'``llvm.powi.*``' Intrinsic 11508^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11509 11510Syntax: 11511""""""" 11512 11513This is an overloaded intrinsic. You can use ``llvm.powi`` on any 11514floating-point or vector of floating-point type. Not all targets support 11515all types however. 11516 11517:: 11518 11519 declare float @llvm.powi.f32(float %Val, i32 %power) 11520 declare double @llvm.powi.f64(double %Val, i32 %power) 11521 declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power) 11522 declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power) 11523 declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power) 11524 11525Overview: 11526""""""""" 11527 11528The '``llvm.powi.*``' intrinsics return the first operand raised to the 11529specified (positive or negative) power. The order of evaluation of 11530multiplications is not defined. When a vector of floating-point type is 11531used, the second argument remains a scalar integer value. 11532 11533Arguments: 11534"""""""""" 11535 11536The second argument is an integer power, and the first is a value to 11537raise to that power. 11538 11539Semantics: 11540"""""""""" 11541 11542This function returns the first value raised to the second power with an 11543unspecified sequence of rounding operations. 11544 11545'``llvm.sin.*``' Intrinsic 11546^^^^^^^^^^^^^^^^^^^^^^^^^^ 11547 11548Syntax: 11549""""""" 11550 11551This is an overloaded intrinsic. You can use ``llvm.sin`` on any 11552floating-point or vector of floating-point type. Not all targets support 11553all types however. 11554 11555:: 11556 11557 declare float @llvm.sin.f32(float %Val) 11558 declare double @llvm.sin.f64(double %Val) 11559 declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val) 11560 declare fp128 @llvm.sin.f128(fp128 %Val) 11561 declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val) 11562 11563Overview: 11564""""""""" 11565 11566The '``llvm.sin.*``' intrinsics return the sine of the operand. 11567 11568Arguments: 11569"""""""""" 11570 11571The argument and return value are floating-point numbers of the same type. 11572 11573Semantics: 11574"""""""""" 11575 11576Return the same value as a corresponding libm '``sin``' function but without 11577trapping or setting ``errno``. 11578 11579When specified with the fast-math-flag 'afn', the result may be approximated 11580using a less accurate calculation. 11581 11582'``llvm.cos.*``' Intrinsic 11583^^^^^^^^^^^^^^^^^^^^^^^^^^ 11584 11585Syntax: 11586""""""" 11587 11588This is an overloaded intrinsic. You can use ``llvm.cos`` on any 11589floating-point or vector of floating-point type. Not all targets support 11590all types however. 11591 11592:: 11593 11594 declare float @llvm.cos.f32(float %Val) 11595 declare double @llvm.cos.f64(double %Val) 11596 declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val) 11597 declare fp128 @llvm.cos.f128(fp128 %Val) 11598 declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val) 11599 11600Overview: 11601""""""""" 11602 11603The '``llvm.cos.*``' intrinsics return the cosine of the operand. 11604 11605Arguments: 11606"""""""""" 11607 11608The argument and return value are floating-point numbers of the same type. 11609 11610Semantics: 11611"""""""""" 11612 11613Return the same value as a corresponding libm '``cos``' function but without 11614trapping or setting ``errno``. 11615 11616When specified with the fast-math-flag 'afn', the result may be approximated 11617using a less accurate calculation. 11618 11619'``llvm.pow.*``' Intrinsic 11620^^^^^^^^^^^^^^^^^^^^^^^^^^ 11621 11622Syntax: 11623""""""" 11624 11625This is an overloaded intrinsic. You can use ``llvm.pow`` on any 11626floating-point or vector of floating-point type. Not all targets support 11627all types however. 11628 11629:: 11630 11631 declare float @llvm.pow.f32(float %Val, float %Power) 11632 declare double @llvm.pow.f64(double %Val, double %Power) 11633 declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power) 11634 declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power) 11635 declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power) 11636 11637Overview: 11638""""""""" 11639 11640The '``llvm.pow.*``' intrinsics return the first operand raised to the 11641specified (positive or negative) power. 11642 11643Arguments: 11644"""""""""" 11645 11646The arguments and return value are floating-point numbers of the same type. 11647 11648Semantics: 11649"""""""""" 11650 11651Return the same value as a corresponding libm '``pow``' function but without 11652trapping or setting ``errno``. 11653 11654When specified with the fast-math-flag 'afn', the result may be approximated 11655using a less accurate calculation. 11656 11657'``llvm.exp.*``' Intrinsic 11658^^^^^^^^^^^^^^^^^^^^^^^^^^ 11659 11660Syntax: 11661""""""" 11662 11663This is an overloaded intrinsic. You can use ``llvm.exp`` on any 11664floating-point or vector of floating-point type. Not all targets support 11665all types however. 11666 11667:: 11668 11669 declare float @llvm.exp.f32(float %Val) 11670 declare double @llvm.exp.f64(double %Val) 11671 declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val) 11672 declare fp128 @llvm.exp.f128(fp128 %Val) 11673 declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val) 11674 11675Overview: 11676""""""""" 11677 11678The '``llvm.exp.*``' intrinsics compute the base-e exponential of the specified 11679value. 11680 11681Arguments: 11682"""""""""" 11683 11684The argument and return value are floating-point numbers of the same type. 11685 11686Semantics: 11687"""""""""" 11688 11689Return the same value as a corresponding libm '``exp``' function but without 11690trapping or setting ``errno``. 11691 11692When specified with the fast-math-flag 'afn', the result may be approximated 11693using a less accurate calculation. 11694 11695'``llvm.exp2.*``' Intrinsic 11696^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11697 11698Syntax: 11699""""""" 11700 11701This is an overloaded intrinsic. You can use ``llvm.exp2`` on any 11702floating-point or vector of floating-point type. Not all targets support 11703all types however. 11704 11705:: 11706 11707 declare float @llvm.exp2.f32(float %Val) 11708 declare double @llvm.exp2.f64(double %Val) 11709 declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val) 11710 declare fp128 @llvm.exp2.f128(fp128 %Val) 11711 declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val) 11712 11713Overview: 11714""""""""" 11715 11716The '``llvm.exp2.*``' intrinsics compute the base-2 exponential of the 11717specified value. 11718 11719Arguments: 11720"""""""""" 11721 11722The argument and return value are floating-point numbers of the same type. 11723 11724Semantics: 11725"""""""""" 11726 11727Return the same value as a corresponding libm '``exp2``' function but without 11728trapping or setting ``errno``. 11729 11730When specified with the fast-math-flag 'afn', the result may be approximated 11731using a less accurate calculation. 11732 11733'``llvm.log.*``' Intrinsic 11734^^^^^^^^^^^^^^^^^^^^^^^^^^ 11735 11736Syntax: 11737""""""" 11738 11739This is an overloaded intrinsic. You can use ``llvm.log`` on any 11740floating-point or vector of floating-point type. Not all targets support 11741all types however. 11742 11743:: 11744 11745 declare float @llvm.log.f32(float %Val) 11746 declare double @llvm.log.f64(double %Val) 11747 declare x86_fp80 @llvm.log.f80(x86_fp80 %Val) 11748 declare fp128 @llvm.log.f128(fp128 %Val) 11749 declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val) 11750 11751Overview: 11752""""""""" 11753 11754The '``llvm.log.*``' intrinsics compute the base-e logarithm of the specified 11755value. 11756 11757Arguments: 11758"""""""""" 11759 11760The argument and return value are floating-point numbers of the same type. 11761 11762Semantics: 11763"""""""""" 11764 11765Return the same value as a corresponding libm '``log``' function but without 11766trapping or setting ``errno``. 11767 11768When specified with the fast-math-flag 'afn', the result may be approximated 11769using a less accurate calculation. 11770 11771'``llvm.log10.*``' Intrinsic 11772^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11773 11774Syntax: 11775""""""" 11776 11777This is an overloaded intrinsic. You can use ``llvm.log10`` on any 11778floating-point or vector of floating-point type. Not all targets support 11779all types however. 11780 11781:: 11782 11783 declare float @llvm.log10.f32(float %Val) 11784 declare double @llvm.log10.f64(double %Val) 11785 declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val) 11786 declare fp128 @llvm.log10.f128(fp128 %Val) 11787 declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val) 11788 11789Overview: 11790""""""""" 11791 11792The '``llvm.log10.*``' intrinsics compute the base-10 logarithm of the 11793specified value. 11794 11795Arguments: 11796"""""""""" 11797 11798The argument and return value are floating-point numbers of the same type. 11799 11800Semantics: 11801"""""""""" 11802 11803Return the same value as a corresponding libm '``log10``' function but without 11804trapping or setting ``errno``. 11805 11806When specified with the fast-math-flag 'afn', the result may be approximated 11807using a less accurate calculation. 11808 11809'``llvm.log2.*``' Intrinsic 11810^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11811 11812Syntax: 11813""""""" 11814 11815This is an overloaded intrinsic. You can use ``llvm.log2`` on any 11816floating-point or vector of floating-point type. Not all targets support 11817all types however. 11818 11819:: 11820 11821 declare float @llvm.log2.f32(float %Val) 11822 declare double @llvm.log2.f64(double %Val) 11823 declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val) 11824 declare fp128 @llvm.log2.f128(fp128 %Val) 11825 declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val) 11826 11827Overview: 11828""""""""" 11829 11830The '``llvm.log2.*``' intrinsics compute the base-2 logarithm of the specified 11831value. 11832 11833Arguments: 11834"""""""""" 11835 11836The argument and return value are floating-point numbers of the same type. 11837 11838Semantics: 11839"""""""""" 11840 11841Return the same value as a corresponding libm '``log2``' function but without 11842trapping or setting ``errno``. 11843 11844When specified with the fast-math-flag 'afn', the result may be approximated 11845using a less accurate calculation. 11846 11847'``llvm.fma.*``' Intrinsic 11848^^^^^^^^^^^^^^^^^^^^^^^^^^ 11849 11850Syntax: 11851""""""" 11852 11853This is an overloaded intrinsic. You can use ``llvm.fma`` on any 11854floating-point or vector of floating-point type. Not all targets support 11855all types however. 11856 11857:: 11858 11859 declare float @llvm.fma.f32(float %a, float %b, float %c) 11860 declare double @llvm.fma.f64(double %a, double %b, double %c) 11861 declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c) 11862 declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c) 11863 declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c) 11864 11865Overview: 11866""""""""" 11867 11868The '``llvm.fma.*``' intrinsics perform the fused multiply-add operation. 11869 11870Arguments: 11871"""""""""" 11872 11873The arguments and return value are floating-point numbers of the same type. 11874 11875Semantics: 11876"""""""""" 11877 11878Return the same value as a corresponding libm '``fma``' function but without 11879trapping or setting ``errno``. 11880 11881When specified with the fast-math-flag 'afn', the result may be approximated 11882using a less accurate calculation. 11883 11884'``llvm.fabs.*``' Intrinsic 11885^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11886 11887Syntax: 11888""""""" 11889 11890This is an overloaded intrinsic. You can use ``llvm.fabs`` on any 11891floating-point or vector of floating-point type. Not all targets support 11892all types however. 11893 11894:: 11895 11896 declare float @llvm.fabs.f32(float %Val) 11897 declare double @llvm.fabs.f64(double %Val) 11898 declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val) 11899 declare fp128 @llvm.fabs.f128(fp128 %Val) 11900 declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val) 11901 11902Overview: 11903""""""""" 11904 11905The '``llvm.fabs.*``' intrinsics return the absolute value of the 11906operand. 11907 11908Arguments: 11909"""""""""" 11910 11911The argument and return value are floating-point numbers of the same 11912type. 11913 11914Semantics: 11915"""""""""" 11916 11917This function returns the same values as the libm ``fabs`` functions 11918would, and handles error conditions in the same way. 11919 11920'``llvm.minnum.*``' Intrinsic 11921^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11922 11923Syntax: 11924""""""" 11925 11926This is an overloaded intrinsic. You can use ``llvm.minnum`` on any 11927floating-point or vector of floating-point type. Not all targets support 11928all types however. 11929 11930:: 11931 11932 declare float @llvm.minnum.f32(float %Val0, float %Val1) 11933 declare double @llvm.minnum.f64(double %Val0, double %Val1) 11934 declare x86_fp80 @llvm.minnum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 11935 declare fp128 @llvm.minnum.f128(fp128 %Val0, fp128 %Val1) 11936 declare ppc_fp128 @llvm.minnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 11937 11938Overview: 11939""""""""" 11940 11941The '``llvm.minnum.*``' intrinsics return the minimum of the two 11942arguments. 11943 11944 11945Arguments: 11946"""""""""" 11947 11948The arguments and return value are floating-point numbers of the same 11949type. 11950 11951Semantics: 11952"""""""""" 11953 11954Follows the IEEE-754 semantics for minNum, except for handling of 11955signaling NaNs. This match's the behavior of libm's fmin. 11956 11957If either operand is a NaN, returns the other non-NaN operand. Returns 11958NaN only if both operands are NaN. The returned NaN is always 11959quiet. If the operands compare equal, returns a value that compares 11960equal to both operands. This means that fmin(+/-0.0, +/-0.0) could 11961return either -0.0 or 0.0. 11962 11963Unlike the IEEE-754 2008 behavior, this does not distinguish between 11964signaling and quiet NaN inputs. If a target's implementation follows 11965the standard and returns a quiet NaN if either input is a signaling 11966NaN, the intrinsic lowering is responsible for quieting the inputs to 11967correctly return the non-NaN input (e.g. by using the equivalent of 11968``llvm.canonicalize``). 11969 11970 11971'``llvm.maxnum.*``' Intrinsic 11972^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11973 11974Syntax: 11975""""""" 11976 11977This is an overloaded intrinsic. You can use ``llvm.maxnum`` on any 11978floating-point or vector of floating-point type. Not all targets support 11979all types however. 11980 11981:: 11982 11983 declare float @llvm.maxnum.f32(float %Val0, float %Val1l) 11984 declare double @llvm.maxnum.f64(double %Val0, double %Val1) 11985 declare x86_fp80 @llvm.maxnum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 11986 declare fp128 @llvm.maxnum.f128(fp128 %Val0, fp128 %Val1) 11987 declare ppc_fp128 @llvm.maxnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 11988 11989Overview: 11990""""""""" 11991 11992The '``llvm.maxnum.*``' intrinsics return the maximum of the two 11993arguments. 11994 11995 11996Arguments: 11997"""""""""" 11998 11999The arguments and return value are floating-point numbers of the same 12000type. 12001 12002Semantics: 12003"""""""""" 12004Follows the IEEE-754 semantics for maxNum except for the handling of 12005signaling NaNs. This matches the behavior of libm's fmax. 12006 12007If either operand is a NaN, returns the other non-NaN operand. Returns 12008NaN only if both operands are NaN. The returned NaN is always 12009quiet. If the operands compare equal, returns a value that compares 12010equal to both operands. This means that fmax(+/-0.0, +/-0.0) could 12011return either -0.0 or 0.0. 12012 12013Unlike the IEEE-754 2008 behavior, this does not distinguish between 12014signaling and quiet NaN inputs. If a target's implementation follows 12015the standard and returns a quiet NaN if either input is a signaling 12016NaN, the intrinsic lowering is responsible for quieting the inputs to 12017correctly return the non-NaN input (e.g. by using the equivalent of 12018``llvm.canonicalize``). 12019 12020'``llvm.minimum.*``' Intrinsic 12021^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12022 12023Syntax: 12024""""""" 12025 12026This is an overloaded intrinsic. You can use ``llvm.minimum`` on any 12027floating-point or vector of floating-point type. Not all targets support 12028all types however. 12029 12030:: 12031 12032 declare float @llvm.minimum.f32(float %Val0, float %Val1) 12033 declare double @llvm.minimum.f64(double %Val0, double %Val1) 12034 declare x86_fp80 @llvm.minimum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 12035 declare fp128 @llvm.minimum.f128(fp128 %Val0, fp128 %Val1) 12036 declare ppc_fp128 @llvm.minimum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 12037 12038Overview: 12039""""""""" 12040 12041The '``llvm.minimum.*``' intrinsics return the minimum of the two 12042arguments, propagating NaNs and treating -0.0 as less than +0.0. 12043 12044 12045Arguments: 12046"""""""""" 12047 12048The arguments and return value are floating-point numbers of the same 12049type. 12050 12051Semantics: 12052"""""""""" 12053If either operand is a NaN, returns NaN. Otherwise returns the lesser 12054of the two arguments. -0.0 is considered to be less than +0.0 for this 12055intrinsic. Note that these are the semantics specified in the draft of 12056IEEE 754-2018. 12057 12058'``llvm.maximum.*``' Intrinsic 12059^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12060 12061Syntax: 12062""""""" 12063 12064This is an overloaded intrinsic. You can use ``llvm.maximum`` on any 12065floating-point or vector of floating-point type. Not all targets support 12066all types however. 12067 12068:: 12069 12070 declare float @llvm.maximum.f32(float %Val0, float %Val1) 12071 declare double @llvm.maximum.f64(double %Val0, double %Val1) 12072 declare x86_fp80 @llvm.maximum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 12073 declare fp128 @llvm.maximum.f128(fp128 %Val0, fp128 %Val1) 12074 declare ppc_fp128 @llvm.maximum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 12075 12076Overview: 12077""""""""" 12078 12079The '``llvm.maximum.*``' intrinsics return the maximum of the two 12080arguments, propagating NaNs and treating -0.0 as less than +0.0. 12081 12082 12083Arguments: 12084"""""""""" 12085 12086The arguments and return value are floating-point numbers of the same 12087type. 12088 12089Semantics: 12090"""""""""" 12091If either operand is a NaN, returns NaN. Otherwise returns the greater 12092of the two arguments. -0.0 is considered to be less than +0.0 for this 12093intrinsic. Note that these are the semantics specified in the draft of 12094IEEE 754-2018. 12095 12096'``llvm.copysign.*``' Intrinsic 12097^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12098 12099Syntax: 12100""""""" 12101 12102This is an overloaded intrinsic. You can use ``llvm.copysign`` on any 12103floating-point or vector of floating-point type. Not all targets support 12104all types however. 12105 12106:: 12107 12108 declare float @llvm.copysign.f32(float %Mag, float %Sgn) 12109 declare double @llvm.copysign.f64(double %Mag, double %Sgn) 12110 declare x86_fp80 @llvm.copysign.f80(x86_fp80 %Mag, x86_fp80 %Sgn) 12111 declare fp128 @llvm.copysign.f128(fp128 %Mag, fp128 %Sgn) 12112 declare ppc_fp128 @llvm.copysign.ppcf128(ppc_fp128 %Mag, ppc_fp128 %Sgn) 12113 12114Overview: 12115""""""""" 12116 12117The '``llvm.copysign.*``' intrinsics return a value with the magnitude of the 12118first operand and the sign of the second operand. 12119 12120Arguments: 12121"""""""""" 12122 12123The arguments and return value are floating-point numbers of the same 12124type. 12125 12126Semantics: 12127"""""""""" 12128 12129This function returns the same values as the libm ``copysign`` 12130functions would, and handles error conditions in the same way. 12131 12132'``llvm.floor.*``' Intrinsic 12133^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12134 12135Syntax: 12136""""""" 12137 12138This is an overloaded intrinsic. You can use ``llvm.floor`` on any 12139floating-point or vector of floating-point type. Not all targets support 12140all types however. 12141 12142:: 12143 12144 declare float @llvm.floor.f32(float %Val) 12145 declare double @llvm.floor.f64(double %Val) 12146 declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val) 12147 declare fp128 @llvm.floor.f128(fp128 %Val) 12148 declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val) 12149 12150Overview: 12151""""""""" 12152 12153The '``llvm.floor.*``' intrinsics return the floor of the operand. 12154 12155Arguments: 12156"""""""""" 12157 12158The argument and return value are floating-point numbers of the same 12159type. 12160 12161Semantics: 12162"""""""""" 12163 12164This function returns the same values as the libm ``floor`` functions 12165would, and handles error conditions in the same way. 12166 12167'``llvm.ceil.*``' Intrinsic 12168^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12169 12170Syntax: 12171""""""" 12172 12173This is an overloaded intrinsic. You can use ``llvm.ceil`` on any 12174floating-point or vector of floating-point type. Not all targets support 12175all types however. 12176 12177:: 12178 12179 declare float @llvm.ceil.f32(float %Val) 12180 declare double @llvm.ceil.f64(double %Val) 12181 declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val) 12182 declare fp128 @llvm.ceil.f128(fp128 %Val) 12183 declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val) 12184 12185Overview: 12186""""""""" 12187 12188The '``llvm.ceil.*``' intrinsics return the ceiling of the operand. 12189 12190Arguments: 12191"""""""""" 12192 12193The argument and return value are floating-point numbers of the same 12194type. 12195 12196Semantics: 12197"""""""""" 12198 12199This function returns the same values as the libm ``ceil`` functions 12200would, and handles error conditions in the same way. 12201 12202'``llvm.trunc.*``' Intrinsic 12203^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12204 12205Syntax: 12206""""""" 12207 12208This is an overloaded intrinsic. You can use ``llvm.trunc`` on any 12209floating-point or vector of floating-point type. Not all targets support 12210all types however. 12211 12212:: 12213 12214 declare float @llvm.trunc.f32(float %Val) 12215 declare double @llvm.trunc.f64(double %Val) 12216 declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val) 12217 declare fp128 @llvm.trunc.f128(fp128 %Val) 12218 declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val) 12219 12220Overview: 12221""""""""" 12222 12223The '``llvm.trunc.*``' intrinsics returns the operand rounded to the 12224nearest integer not larger in magnitude than the operand. 12225 12226Arguments: 12227"""""""""" 12228 12229The argument and return value are floating-point numbers of the same 12230type. 12231 12232Semantics: 12233"""""""""" 12234 12235This function returns the same values as the libm ``trunc`` functions 12236would, and handles error conditions in the same way. 12237 12238'``llvm.rint.*``' Intrinsic 12239^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12240 12241Syntax: 12242""""""" 12243 12244This is an overloaded intrinsic. You can use ``llvm.rint`` on any 12245floating-point or vector of floating-point type. Not all targets support 12246all types however. 12247 12248:: 12249 12250 declare float @llvm.rint.f32(float %Val) 12251 declare double @llvm.rint.f64(double %Val) 12252 declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val) 12253 declare fp128 @llvm.rint.f128(fp128 %Val) 12254 declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val) 12255 12256Overview: 12257""""""""" 12258 12259The '``llvm.rint.*``' intrinsics returns the operand rounded to the 12260nearest integer. It may raise an inexact floating-point exception if the 12261operand isn't an integer. 12262 12263Arguments: 12264"""""""""" 12265 12266The argument and return value are floating-point numbers of the same 12267type. 12268 12269Semantics: 12270"""""""""" 12271 12272This function returns the same values as the libm ``rint`` functions 12273would, and handles error conditions in the same way. 12274 12275'``llvm.nearbyint.*``' Intrinsic 12276^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12277 12278Syntax: 12279""""""" 12280 12281This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any 12282floating-point or vector of floating-point type. Not all targets support 12283all types however. 12284 12285:: 12286 12287 declare float @llvm.nearbyint.f32(float %Val) 12288 declare double @llvm.nearbyint.f64(double %Val) 12289 declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val) 12290 declare fp128 @llvm.nearbyint.f128(fp128 %Val) 12291 declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val) 12292 12293Overview: 12294""""""""" 12295 12296The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the 12297nearest integer. 12298 12299Arguments: 12300"""""""""" 12301 12302The argument and return value are floating-point numbers of the same 12303type. 12304 12305Semantics: 12306"""""""""" 12307 12308This function returns the same values as the libm ``nearbyint`` 12309functions would, and handles error conditions in the same way. 12310 12311'``llvm.round.*``' Intrinsic 12312^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12313 12314Syntax: 12315""""""" 12316 12317This is an overloaded intrinsic. You can use ``llvm.round`` on any 12318floating-point or vector of floating-point type. Not all targets support 12319all types however. 12320 12321:: 12322 12323 declare float @llvm.round.f32(float %Val) 12324 declare double @llvm.round.f64(double %Val) 12325 declare x86_fp80 @llvm.round.f80(x86_fp80 %Val) 12326 declare fp128 @llvm.round.f128(fp128 %Val) 12327 declare ppc_fp128 @llvm.round.ppcf128(ppc_fp128 %Val) 12328 12329Overview: 12330""""""""" 12331 12332The '``llvm.round.*``' intrinsics returns the operand rounded to the 12333nearest integer. 12334 12335Arguments: 12336"""""""""" 12337 12338The argument and return value are floating-point numbers of the same 12339type. 12340 12341Semantics: 12342"""""""""" 12343 12344This function returns the same values as the libm ``round`` 12345functions would, and handles error conditions in the same way. 12346 12347Bit Manipulation Intrinsics 12348--------------------------- 12349 12350LLVM provides intrinsics for a few important bit manipulation 12351operations. These allow efficient code generation for some algorithms. 12352 12353'``llvm.bitreverse.*``' Intrinsics 12354^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12355 12356Syntax: 12357""""""" 12358 12359This is an overloaded intrinsic function. You can use bitreverse on any 12360integer type. 12361 12362:: 12363 12364 declare i16 @llvm.bitreverse.i16(i16 <id>) 12365 declare i32 @llvm.bitreverse.i32(i32 <id>) 12366 declare i64 @llvm.bitreverse.i64(i64 <id>) 12367 declare <4 x i32> @llvm.bitreverse.v4i32(<4 x i32> <id>) 12368 12369Overview: 12370""""""""" 12371 12372The '``llvm.bitreverse``' family of intrinsics is used to reverse the 12373bitpattern of an integer value or vector of integer values; for example 12374``0b10110110`` becomes ``0b01101101``. 12375 12376Semantics: 12377"""""""""" 12378 12379The ``llvm.bitreverse.iN`` intrinsic returns an iN value that has bit 12380``M`` in the input moved to bit ``N-M`` in the output. The vector 12381intrinsics, such as ``llvm.bitreverse.v4i32``, operate on a per-element 12382basis and the element order is not affected. 12383 12384'``llvm.bswap.*``' Intrinsics 12385^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12386 12387Syntax: 12388""""""" 12389 12390This is an overloaded intrinsic function. You can use bswap on any 12391integer type that is an even number of bytes (i.e. BitWidth % 16 == 0). 12392 12393:: 12394 12395 declare i16 @llvm.bswap.i16(i16 <id>) 12396 declare i32 @llvm.bswap.i32(i32 <id>) 12397 declare i64 @llvm.bswap.i64(i64 <id>) 12398 declare <4 x i32> @llvm.bswap.v4i32(<4 x i32> <id>) 12399 12400Overview: 12401""""""""" 12402 12403The '``llvm.bswap``' family of intrinsics is used to byte swap an integer 12404value or vector of integer values with an even number of bytes (positive 12405multiple of 16 bits). 12406 12407Semantics: 12408"""""""""" 12409 12410The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high 12411and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32`` 12412intrinsic returns an i32 value that has the four bytes of the input i32 12413swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the 12414returned i32 will have its bytes in 3, 2, 1, 0 order. The 12415``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this 12416concept to additional even-byte lengths (6 bytes, 8 bytes and more, 12417respectively). The vector intrinsics, such as ``llvm.bswap.v4i32``, 12418operate on a per-element basis and the element order is not affected. 12419 12420'``llvm.ctpop.*``' Intrinsic 12421^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12422 12423Syntax: 12424""""""" 12425 12426This is an overloaded intrinsic. You can use llvm.ctpop on any integer 12427bit width, or on any vector with integer elements. Not all targets 12428support all bit widths or vector types, however. 12429 12430:: 12431 12432 declare i8 @llvm.ctpop.i8(i8 <src>) 12433 declare i16 @llvm.ctpop.i16(i16 <src>) 12434 declare i32 @llvm.ctpop.i32(i32 <src>) 12435 declare i64 @llvm.ctpop.i64(i64 <src>) 12436 declare i256 @llvm.ctpop.i256(i256 <src>) 12437 declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>) 12438 12439Overview: 12440""""""""" 12441 12442The '``llvm.ctpop``' family of intrinsics counts the number of bits set 12443in a value. 12444 12445Arguments: 12446"""""""""" 12447 12448The only argument is the value to be counted. The argument may be of any 12449integer type, or a vector with integer elements. The return type must 12450match the argument type. 12451 12452Semantics: 12453"""""""""" 12454 12455The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within 12456each element of a vector. 12457 12458'``llvm.ctlz.*``' Intrinsic 12459^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12460 12461Syntax: 12462""""""" 12463 12464This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any 12465integer bit width, or any vector whose elements are integers. Not all 12466targets support all bit widths or vector types, however. 12467 12468:: 12469 12470 declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>) 12471 declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>) 12472 declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>) 12473 declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>) 12474 declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>) 12475 declare <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) 12476 12477Overview: 12478""""""""" 12479 12480The '``llvm.ctlz``' family of intrinsic functions counts the number of 12481leading zeros in a variable. 12482 12483Arguments: 12484"""""""""" 12485 12486The first argument is the value to be counted. This argument may be of 12487any integer type, or a vector with integer element type. The return 12488type must match the first argument type. 12489 12490The second argument must be a constant and is a flag to indicate whether 12491the intrinsic should ensure that a zero as the first argument produces a 12492defined result. Historically some architectures did not provide a 12493defined result for zero values as efficiently, and many algorithms are 12494now predicated on avoiding zero-value inputs. 12495 12496Semantics: 12497"""""""""" 12498 12499The '``llvm.ctlz``' intrinsic counts the leading (most significant) 12500zeros in a variable, or within each element of the vector. If 12501``src == 0`` then the result is the size in bits of the type of ``src`` 12502if ``is_zero_undef == 0`` and ``undef`` otherwise. For example, 12503``llvm.ctlz(i32 2) = 30``. 12504 12505'``llvm.cttz.*``' Intrinsic 12506^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12507 12508Syntax: 12509""""""" 12510 12511This is an overloaded intrinsic. You can use ``llvm.cttz`` on any 12512integer bit width, or any vector of integer elements. Not all targets 12513support all bit widths or vector types, however. 12514 12515:: 12516 12517 declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>) 12518 declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>) 12519 declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>) 12520 declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>) 12521 declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>) 12522 declare <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) 12523 12524Overview: 12525""""""""" 12526 12527The '``llvm.cttz``' family of intrinsic functions counts the number of 12528trailing zeros. 12529 12530Arguments: 12531"""""""""" 12532 12533The first argument is the value to be counted. This argument may be of 12534any integer type, or a vector with integer element type. The return 12535type must match the first argument type. 12536 12537The second argument must be a constant and is a flag to indicate whether 12538the intrinsic should ensure that a zero as the first argument produces a 12539defined result. Historically some architectures did not provide a 12540defined result for zero values as efficiently, and many algorithms are 12541now predicated on avoiding zero-value inputs. 12542 12543Semantics: 12544"""""""""" 12545 12546The '``llvm.cttz``' intrinsic counts the trailing (least significant) 12547zeros in a variable, or within each element of a vector. If ``src == 0`` 12548then the result is the size in bits of the type of ``src`` if 12549``is_zero_undef == 0`` and ``undef`` otherwise. For example, 12550``llvm.cttz(2) = 1``. 12551 12552.. _int_overflow: 12553 12554'``llvm.fshl.*``' Intrinsic 12555^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12556 12557Syntax: 12558""""""" 12559 12560This is an overloaded intrinsic. You can use ``llvm.fshl`` on any 12561integer bit width or any vector of integer elements. Not all targets 12562support all bit widths or vector types, however. 12563 12564:: 12565 12566 declare i8 @llvm.fshl.i8 (i8 %a, i8 %b, i8 %c) 12567 declare i67 @llvm.fshl.i67(i67 %a, i67 %b, i67 %c) 12568 declare <2 x i32> @llvm.fshl.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c) 12569 12570Overview: 12571""""""""" 12572 12573The '``llvm.fshl``' family of intrinsic functions performs a funnel shift left: 12574the first two values are concatenated as { %a : %b } (%a is the most significant 12575bits of the wide value), the combined value is shifted left, and the most 12576significant bits are extracted to produce a result that is the same size as the 12577original arguments. If the first 2 arguments are identical, this is equivalent 12578to a rotate left operation. For vector types, the operation occurs for each 12579element of the vector. The shift argument is treated as an unsigned amount 12580modulo the element size of the arguments. 12581 12582Arguments: 12583"""""""""" 12584 12585The first two arguments are the values to be concatenated. The third 12586argument is the shift amount. The arguments may be any integer type or a 12587vector with integer element type. All arguments and the return value must 12588have the same type. 12589 12590Example: 12591"""""""" 12592 12593.. code-block:: text 12594 12595 %r = call i8 @llvm.fshl.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: msb_extract((concat(x, y) << (z % 8)), 8) 12596 %r = call i8 @llvm.fshl.i8(i8 255, i8 0, i8 15) ; %r = i8: 128 (0b10000000) 12597 %r = call i8 @llvm.fshl.i8(i8 15, i8 15, i8 11) ; %r = i8: 120 (0b01111000) 12598 %r = call i8 @llvm.fshl.i8(i8 0, i8 255, i8 8) ; %r = i8: 0 (0b00000000) 12599 12600'``llvm.fshr.*``' Intrinsic 12601^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12602 12603Syntax: 12604""""""" 12605 12606This is an overloaded intrinsic. You can use ``llvm.fshr`` on any 12607integer bit width or any vector of integer elements. Not all targets 12608support all bit widths or vector types, however. 12609 12610:: 12611 12612 declare i8 @llvm.fshr.i8 (i8 %a, i8 %b, i8 %c) 12613 declare i67 @llvm.fshr.i67(i67 %a, i67 %b, i67 %c) 12614 declare <2 x i32> @llvm.fshr.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c) 12615 12616Overview: 12617""""""""" 12618 12619The '``llvm.fshr``' family of intrinsic functions performs a funnel shift right: 12620the first two values are concatenated as { %a : %b } (%a is the most significant 12621bits of the wide value), the combined value is shifted right, and the least 12622significant bits are extracted to produce a result that is the same size as the 12623original arguments. If the first 2 arguments are identical, this is equivalent 12624to a rotate right operation. For vector types, the operation occurs for each 12625element of the vector. The shift argument is treated as an unsigned amount 12626modulo the element size of the arguments. 12627 12628Arguments: 12629"""""""""" 12630 12631The first two arguments are the values to be concatenated. The third 12632argument is the shift amount. The arguments may be any integer type or a 12633vector with integer element type. All arguments and the return value must 12634have the same type. 12635 12636Example: 12637"""""""" 12638 12639.. code-block:: text 12640 12641 %r = call i8 @llvm.fshr.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: lsb_extract((concat(x, y) >> (z % 8)), 8) 12642 %r = call i8 @llvm.fshr.i8(i8 255, i8 0, i8 15) ; %r = i8: 254 (0b11111110) 12643 %r = call i8 @llvm.fshr.i8(i8 15, i8 15, i8 11) ; %r = i8: 225 (0b11100001) 12644 %r = call i8 @llvm.fshr.i8(i8 0, i8 255, i8 8) ; %r = i8: 255 (0b11111111) 12645 12646Arithmetic with Overflow Intrinsics 12647----------------------------------- 12648 12649LLVM provides intrinsics for fast arithmetic overflow checking. 12650 12651Each of these intrinsics returns a two-element struct. The first 12652element of this struct contains the result of the corresponding 12653arithmetic operation modulo 2\ :sup:`n`\ , where n is the bit width of 12654the result. Therefore, for example, the first element of the struct 12655returned by ``llvm.sadd.with.overflow.i32`` is always the same as the 12656result of a 32-bit ``add`` instruction with the same operands, where 12657the ``add`` is *not* modified by an ``nsw`` or ``nuw`` flag. 12658 12659The second element of the result is an ``i1`` that is 1 if the 12660arithmetic operation overflowed and 0 otherwise. An operation 12661overflows if, for any values of its operands ``A`` and ``B`` and for 12662any ``N`` larger than the operands' width, ``ext(A op B) to iN`` is 12663not equal to ``(ext(A) to iN) op (ext(B) to iN)`` where ``ext`` is 12664``sext`` for signed overflow and ``zext`` for unsigned overflow, and 12665``op`` is the underlying arithmetic operation. 12666 12667The behavior of these intrinsics is well-defined for all argument 12668values. 12669 12670'``llvm.sadd.with.overflow.*``' Intrinsics 12671^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12672 12673Syntax: 12674""""""" 12675 12676This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow`` 12677on any integer bit width or vectors of integers. 12678 12679:: 12680 12681 declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) 12682 declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 12683 declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b) 12684 declare {<4 x i32>, <4 x i1>} @llvm.sadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 12685 12686Overview: 12687""""""""" 12688 12689The '``llvm.sadd.with.overflow``' family of intrinsic functions perform 12690a signed addition of the two arguments, and indicate whether an overflow 12691occurred during the signed summation. 12692 12693Arguments: 12694"""""""""" 12695 12696The arguments (%a and %b) and the first element of the result structure 12697may be of integer types of any bit width, but they must have the same 12698bit width. The second element of the result structure must be of type 12699``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 12700addition. 12701 12702Semantics: 12703"""""""""" 12704 12705The '``llvm.sadd.with.overflow``' family of intrinsic functions perform 12706a signed addition of the two variables. They return a structure --- the 12707first element of which is the signed summation, and the second element 12708of which is a bit specifying if the signed summation resulted in an 12709overflow. 12710 12711Examples: 12712""""""""" 12713 12714.. code-block:: llvm 12715 12716 %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 12717 %sum = extractvalue {i32, i1} %res, 0 12718 %obit = extractvalue {i32, i1} %res, 1 12719 br i1 %obit, label %overflow, label %normal 12720 12721'``llvm.uadd.with.overflow.*``' Intrinsics 12722^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12723 12724Syntax: 12725""""""" 12726 12727This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow`` 12728on any integer bit width or vectors of integers. 12729 12730:: 12731 12732 declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b) 12733 declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 12734 declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b) 12735 declare {<4 x i32>, <4 x i1>} @llvm.uadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 12736 12737Overview: 12738""""""""" 12739 12740The '``llvm.uadd.with.overflow``' family of intrinsic functions perform 12741an unsigned addition of the two arguments, and indicate whether a carry 12742occurred during the unsigned summation. 12743 12744Arguments: 12745"""""""""" 12746 12747The arguments (%a and %b) and the first element of the result structure 12748may be of integer types of any bit width, but they must have the same 12749bit width. The second element of the result structure must be of type 12750``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 12751addition. 12752 12753Semantics: 12754"""""""""" 12755 12756The '``llvm.uadd.with.overflow``' family of intrinsic functions perform 12757an unsigned addition of the two arguments. They return a structure --- the 12758first element of which is the sum, and the second element of which is a 12759bit specifying if the unsigned summation resulted in a carry. 12760 12761Examples: 12762""""""""" 12763 12764.. code-block:: llvm 12765 12766 %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 12767 %sum = extractvalue {i32, i1} %res, 0 12768 %obit = extractvalue {i32, i1} %res, 1 12769 br i1 %obit, label %carry, label %normal 12770 12771'``llvm.ssub.with.overflow.*``' Intrinsics 12772^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12773 12774Syntax: 12775""""""" 12776 12777This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow`` 12778on any integer bit width or vectors of integers. 12779 12780:: 12781 12782 declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b) 12783 declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 12784 declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b) 12785 declare {<4 x i32>, <4 x i1>} @llvm.ssub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 12786 12787Overview: 12788""""""""" 12789 12790The '``llvm.ssub.with.overflow``' family of intrinsic functions perform 12791a signed subtraction of the two arguments, and indicate whether an 12792overflow occurred during the signed subtraction. 12793 12794Arguments: 12795"""""""""" 12796 12797The arguments (%a and %b) and the first element of the result structure 12798may be of integer types of any bit width, but they must have the same 12799bit width. The second element of the result structure must be of type 12800``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 12801subtraction. 12802 12803Semantics: 12804"""""""""" 12805 12806The '``llvm.ssub.with.overflow``' family of intrinsic functions perform 12807a signed subtraction of the two arguments. They return a structure --- the 12808first element of which is the subtraction, and the second element of 12809which is a bit specifying if the signed subtraction resulted in an 12810overflow. 12811 12812Examples: 12813""""""""" 12814 12815.. code-block:: llvm 12816 12817 %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 12818 %sum = extractvalue {i32, i1} %res, 0 12819 %obit = extractvalue {i32, i1} %res, 1 12820 br i1 %obit, label %overflow, label %normal 12821 12822'``llvm.usub.with.overflow.*``' Intrinsics 12823^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12824 12825Syntax: 12826""""""" 12827 12828This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow`` 12829on any integer bit width or vectors of integers. 12830 12831:: 12832 12833 declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b) 12834 declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 12835 declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b) 12836 declare {<4 x i32>, <4 x i1>} @llvm.usub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 12837 12838Overview: 12839""""""""" 12840 12841The '``llvm.usub.with.overflow``' family of intrinsic functions perform 12842an unsigned subtraction of the two arguments, and indicate whether an 12843overflow occurred during the unsigned subtraction. 12844 12845Arguments: 12846"""""""""" 12847 12848The arguments (%a and %b) and the first element of the result structure 12849may be of integer types of any bit width, but they must have the same 12850bit width. The second element of the result structure must be of type 12851``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 12852subtraction. 12853 12854Semantics: 12855"""""""""" 12856 12857The '``llvm.usub.with.overflow``' family of intrinsic functions perform 12858an unsigned subtraction of the two arguments. They return a structure --- 12859the first element of which is the subtraction, and the second element of 12860which is a bit specifying if the unsigned subtraction resulted in an 12861overflow. 12862 12863Examples: 12864""""""""" 12865 12866.. code-block:: llvm 12867 12868 %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 12869 %sum = extractvalue {i32, i1} %res, 0 12870 %obit = extractvalue {i32, i1} %res, 1 12871 br i1 %obit, label %overflow, label %normal 12872 12873'``llvm.smul.with.overflow.*``' Intrinsics 12874^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12875 12876Syntax: 12877""""""" 12878 12879This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow`` 12880on any integer bit width or vectors of integers. 12881 12882:: 12883 12884 declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b) 12885 declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 12886 declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b) 12887 declare {<4 x i32>, <4 x i1>} @llvm.smul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 12888 12889Overview: 12890""""""""" 12891 12892The '``llvm.smul.with.overflow``' family of intrinsic functions perform 12893a signed multiplication of the two arguments, and indicate whether an 12894overflow occurred during the signed multiplication. 12895 12896Arguments: 12897"""""""""" 12898 12899The arguments (%a and %b) and the first element of the result structure 12900may be of integer types of any bit width, but they must have the same 12901bit width. The second element of the result structure must be of type 12902``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 12903multiplication. 12904 12905Semantics: 12906"""""""""" 12907 12908The '``llvm.smul.with.overflow``' family of intrinsic functions perform 12909a signed multiplication of the two arguments. They return a structure --- 12910the first element of which is the multiplication, and the second element 12911of which is a bit specifying if the signed multiplication resulted in an 12912overflow. 12913 12914Examples: 12915""""""""" 12916 12917.. code-block:: llvm 12918 12919 %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 12920 %sum = extractvalue {i32, i1} %res, 0 12921 %obit = extractvalue {i32, i1} %res, 1 12922 br i1 %obit, label %overflow, label %normal 12923 12924'``llvm.umul.with.overflow.*``' Intrinsics 12925^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12926 12927Syntax: 12928""""""" 12929 12930This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow`` 12931on any integer bit width or vectors of integers. 12932 12933:: 12934 12935 declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b) 12936 declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 12937 declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b) 12938 declare {<4 x i32>, <4 x i1>} @llvm.umul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 12939 12940Overview: 12941""""""""" 12942 12943The '``llvm.umul.with.overflow``' family of intrinsic functions perform 12944a unsigned multiplication of the two arguments, and indicate whether an 12945overflow occurred during the unsigned multiplication. 12946 12947Arguments: 12948"""""""""" 12949 12950The arguments (%a and %b) and the first element of the result structure 12951may be of integer types of any bit width, but they must have the same 12952bit width. The second element of the result structure must be of type 12953``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 12954multiplication. 12955 12956Semantics: 12957"""""""""" 12958 12959The '``llvm.umul.with.overflow``' family of intrinsic functions perform 12960an unsigned multiplication of the two arguments. They return a structure --- 12961the first element of which is the multiplication, and the second 12962element of which is a bit specifying if the unsigned multiplication 12963resulted in an overflow. 12964 12965Examples: 12966""""""""" 12967 12968.. code-block:: llvm 12969 12970 %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 12971 %sum = extractvalue {i32, i1} %res, 0 12972 %obit = extractvalue {i32, i1} %res, 1 12973 br i1 %obit, label %overflow, label %normal 12974 12975Saturation Arithmetic Intrinsics 12976--------------------------------- 12977 12978Saturation arithmetic is a version of arithmetic in which operations are 12979limited to a fixed range between a minimum and maximum value. If the result of 12980an operation is greater than the maximum value, the result is set (or 12981"clamped") to this maximum. If it is below the minimum, it is clamped to this 12982minimum. 12983 12984 12985'``llvm.sadd.sat.*``' Intrinsics 12986^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12987 12988Syntax 12989""""""" 12990 12991This is an overloaded intrinsic. You can use ``llvm.sadd.sat`` 12992on any integer bit width or vectors of integers. 12993 12994:: 12995 12996 declare i16 @llvm.sadd.sat.i16(i16 %a, i16 %b) 12997 declare i32 @llvm.sadd.sat.i32(i32 %a, i32 %b) 12998 declare i64 @llvm.sadd.sat.i64(i64 %a, i64 %b) 12999 declare <4 x i32> @llvm.sadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 13000 13001Overview 13002""""""""" 13003 13004The '``llvm.sadd.sat``' family of intrinsic functions perform signed 13005saturation addition on the 2 arguments. 13006 13007Arguments 13008"""""""""" 13009 13010The arguments (%a and %b) and the result may be of integer types of any bit 13011width, but they must have the same bit width. ``%a`` and ``%b`` are the two 13012values that will undergo signed addition. 13013 13014Semantics: 13015"""""""""" 13016 13017The maximum value this operation can clamp to is the largest signed value 13018representable by the bit width of the arguments. The minimum value is the 13019smallest signed value representable by this bit width. 13020 13021 13022Examples 13023""""""""" 13024 13025.. code-block:: llvm 13026 13027 %res = call i4 @llvm.sadd.sat.i4(i4 1, i4 2) ; %res = 3 13028 %res = call i4 @llvm.sadd.sat.i4(i4 5, i4 6) ; %res = 7 13029 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 2) ; %res = -2 13030 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 -5) ; %res = -8 13031 13032 13033'``llvm.uadd.sat.*``' Intrinsics 13034^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13035 13036Syntax 13037""""""" 13038 13039This is an overloaded intrinsic. You can use ``llvm.uadd.sat`` 13040on any integer bit width or vectors of integers. 13041 13042:: 13043 13044 declare i16 @llvm.uadd.sat.i16(i16 %a, i16 %b) 13045 declare i32 @llvm.uadd.sat.i32(i32 %a, i32 %b) 13046 declare i64 @llvm.uadd.sat.i64(i64 %a, i64 %b) 13047 declare <4 x i32> @llvm.uadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 13048 13049Overview 13050""""""""" 13051 13052The '``llvm.uadd.sat``' family of intrinsic functions perform unsigned 13053saturation addition on the 2 arguments. 13054 13055Arguments 13056"""""""""" 13057 13058The arguments (%a and %b) and the result may be of integer types of any bit 13059width, but they must have the same bit width. ``%a`` and ``%b`` are the two 13060values that will undergo unsigned addition. 13061 13062Semantics: 13063"""""""""" 13064 13065The maximum value this operation can clamp to is the largest unsigned value 13066representable by the bit width of the arguments. Because this is an unsigned 13067operation, the result will never saturate towards zero. 13068 13069 13070Examples 13071""""""""" 13072 13073.. code-block:: llvm 13074 13075 %res = call i4 @llvm.uadd.sat.i4(i4 1, i4 2) ; %res = 3 13076 %res = call i4 @llvm.uadd.sat.i4(i4 5, i4 6) ; %res = 11 13077 %res = call i4 @llvm.uadd.sat.i4(i4 8, i4 8) ; %res = 15 13078 13079 13080'``llvm.ssub.sat.*``' Intrinsics 13081^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13082 13083Syntax 13084""""""" 13085 13086This is an overloaded intrinsic. You can use ``llvm.ssub.sat`` 13087on any integer bit width or vectors of integers. 13088 13089:: 13090 13091 declare i16 @llvm.ssub.sat.i16(i16 %a, i16 %b) 13092 declare i32 @llvm.ssub.sat.i32(i32 %a, i32 %b) 13093 declare i64 @llvm.ssub.sat.i64(i64 %a, i64 %b) 13094 declare <4 x i32> @llvm.ssub.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 13095 13096Overview 13097""""""""" 13098 13099The '``llvm.ssub.sat``' family of intrinsic functions perform signed 13100saturation subtraction on the 2 arguments. 13101 13102Arguments 13103"""""""""" 13104 13105The arguments (%a and %b) and the result may be of integer types of any bit 13106width, but they must have the same bit width. ``%a`` and ``%b`` are the two 13107values that will undergo signed subtraction. 13108 13109Semantics: 13110"""""""""" 13111 13112The maximum value this operation can clamp to is the largest signed value 13113representable by the bit width of the arguments. The minimum value is the 13114smallest signed value representable by this bit width. 13115 13116 13117Examples 13118""""""""" 13119 13120.. code-block:: llvm 13121 13122 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 1) ; %res = 1 13123 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 6) ; %res = -4 13124 %res = call i4 @llvm.ssub.sat.i4(i4 -4, i4 5) ; %res = -8 13125 %res = call i4 @llvm.ssub.sat.i4(i4 4, i4 -5) ; %res = 7 13126 13127 13128'``llvm.usub.sat.*``' Intrinsics 13129^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13130 13131Syntax 13132""""""" 13133 13134This is an overloaded intrinsic. You can use ``llvm.usub.sat`` 13135on any integer bit width or vectors of integers. 13136 13137:: 13138 13139 declare i16 @llvm.usub.sat.i16(i16 %a, i16 %b) 13140 declare i32 @llvm.usub.sat.i32(i32 %a, i32 %b) 13141 declare i64 @llvm.usub.sat.i64(i64 %a, i64 %b) 13142 declare <4 x i32> @llvm.usub.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 13143 13144Overview 13145""""""""" 13146 13147The '``llvm.usub.sat``' family of intrinsic functions perform unsigned 13148saturation subtraction on the 2 arguments. 13149 13150Arguments 13151"""""""""" 13152 13153The arguments (%a and %b) and the result may be of integer types of any bit 13154width, but they must have the same bit width. ``%a`` and ``%b`` are the two 13155values that will undergo unsigned subtraction. 13156 13157Semantics: 13158"""""""""" 13159 13160The minimum value this operation can clamp to is 0, which is the smallest 13161unsigned value representable by the bit width of the unsigned arguments. 13162Because this is an unsigned operation, the result will never saturate towards 13163the largest possible value representable by this bit width. 13164 13165 13166Examples 13167""""""""" 13168 13169.. code-block:: llvm 13170 13171 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 1) ; %res = 1 13172 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 6) ; %res = 0 13173 13174 13175Fixed Point Arithmetic Intrinsics 13176--------------------------------- 13177 13178A fixed point number represents a real data type for a number that has a fixed 13179number of digits after a radix point (equivalent to the decimal point '.'). 13180The number of digits after the radix point is referred as the ``scale``. These 13181are useful for representing fractional values to a specific precision. The 13182following intrinsics perform fixed point arithmetic operations on 2 operands 13183of the same scale, specified as the third argument. 13184 13185 13186'``llvm.smul.fix.*``' Intrinsics 13187^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13188 13189Syntax 13190""""""" 13191 13192This is an overloaded intrinsic. You can use ``llvm.smul.fix`` 13193on any integer bit width or vectors of integers. 13194 13195:: 13196 13197 declare i16 @llvm.smul.fix.i16(i16 %a, i16 %b, i32 %scale) 13198 declare i32 @llvm.smul.fix.i32(i32 %a, i32 %b, i32 %scale) 13199 declare i64 @llvm.smul.fix.i64(i64 %a, i64 %b, i32 %scale) 13200 declare <4 x i32> @llvm.smul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 13201 13202Overview 13203""""""""" 13204 13205The '``llvm.smul.fix``' family of intrinsic functions perform signed 13206fixed point multiplication on 2 arguments of the same scale. 13207 13208Arguments 13209"""""""""" 13210 13211The arguments (%a and %b) and the result may be of integer types of any bit 13212width, but they must have the same bit width. The arguments may also work with 13213int vectors of the same length and int size. ``%a`` and ``%b`` are the two 13214values that will undergo signed fixed point multiplication. The argument 13215``%scale`` represents the scale of both operands, and must be a constant 13216integer. 13217 13218Semantics: 13219"""""""""" 13220 13221This operation performs fixed point multiplication on the 2 arguments of a 13222specified scale. The result will also be returned in the same scale specified 13223in the third argument. 13224 13225If the result value cannot be precisely represented in the given scale, the 13226value is rounded up or down to the closest representable value. The rounding 13227direction is unspecified. 13228 13229It is undefined behavior if the result value does not fit within the range of 13230the fixed point type. 13231 13232 13233Examples 13234""""""""" 13235 13236.. code-block:: llvm 13237 13238 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 13239 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 13240 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 x -1 = -1.5) 13241 13242 ; The result in the following could be rounded up to -2 or down to -2.5 13243 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -3, i32 1) ; %res = -5 (or -4) (1.5 x -1.5 = -2.25) 13244 13245 13246'``llvm.umul.fix.*``' Intrinsics 13247^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13248 13249Syntax 13250""""""" 13251 13252This is an overloaded intrinsic. You can use ``llvm.umul.fix`` 13253on any integer bit width or vectors of integers. 13254 13255:: 13256 13257 declare i16 @llvm.umul.fix.i16(i16 %a, i16 %b, i32 %scale) 13258 declare i32 @llvm.umul.fix.i32(i32 %a, i32 %b, i32 %scale) 13259 declare i64 @llvm.umul.fix.i64(i64 %a, i64 %b, i32 %scale) 13260 declare <4 x i32> @llvm.umul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 13261 13262Overview 13263""""""""" 13264 13265The '``llvm.umul.fix``' family of intrinsic functions perform unsigned 13266fixed point multiplication on 2 arguments of the same scale. 13267 13268Arguments 13269"""""""""" 13270 13271The arguments (%a and %b) and the result may be of integer types of any bit 13272width, but they must have the same bit width. The arguments may also work with 13273int vectors of the same length and int size. ``%a`` and ``%b`` are the two 13274values that will undergo unsigned fixed point multiplication. The argument 13275``%scale`` represents the scale of both operands, and must be a constant 13276integer. 13277 13278Semantics: 13279"""""""""" 13280 13281This operation performs unsigned fixed point multiplication on the 2 arguments of a 13282specified scale. The result will also be returned in the same scale specified 13283in the third argument. 13284 13285If the result value cannot be precisely represented in the given scale, the 13286value is rounded up or down to the closest representable value. The rounding 13287direction is unspecified. 13288 13289It is undefined behavior if the result value does not fit within the range of 13290the fixed point type. 13291 13292 13293Examples 13294""""""""" 13295 13296.. code-block:: llvm 13297 13298 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 13299 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 13300 13301 ; The result in the following could be rounded down to 3.5 or up to 4 13302 %res = call i4 @llvm.umul.fix.i4(i4 15, i4 1, i32 1) ; %res = 7 (or 8) (7.5 x 0.5 = 3.75) 13303 13304 13305Specialised Arithmetic Intrinsics 13306--------------------------------- 13307 13308'``llvm.canonicalize.*``' Intrinsic 13309^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13310 13311Syntax: 13312""""""" 13313 13314:: 13315 13316 declare float @llvm.canonicalize.f32(float %a) 13317 declare double @llvm.canonicalize.f64(double %b) 13318 13319Overview: 13320""""""""" 13321 13322The '``llvm.canonicalize.*``' intrinsic returns the platform specific canonical 13323encoding of a floating-point number. This canonicalization is useful for 13324implementing certain numeric primitives such as frexp. The canonical encoding is 13325defined by IEEE-754-2008 to be: 13326 13327:: 13328 13329 2.1.8 canonical encoding: The preferred encoding of a floating-point 13330 representation in a format. Applied to declets, significands of finite 13331 numbers, infinities, and NaNs, especially in decimal formats. 13332 13333This operation can also be considered equivalent to the IEEE-754-2008 13334conversion of a floating-point value to the same format. NaNs are handled 13335according to section 6.2. 13336 13337Examples of non-canonical encodings: 13338 13339- x87 pseudo denormals, pseudo NaNs, pseudo Infinity, Unnormals. These are 13340 converted to a canonical representation per hardware-specific protocol. 13341- Many normal decimal floating-point numbers have non-canonical alternative 13342 encodings. 13343- Some machines, like GPUs or ARMv7 NEON, do not support subnormal values. 13344 These are treated as non-canonical encodings of zero and will be flushed to 13345 a zero of the same sign by this operation. 13346 13347Note that per IEEE-754-2008 6.2, systems that support signaling NaNs with 13348default exception handling must signal an invalid exception, and produce a 13349quiet NaN result. 13350 13351This function should always be implementable as multiplication by 1.0, provided 13352that the compiler does not constant fold the operation. Likewise, division by 133531.0 and ``llvm.minnum(x, x)`` are possible implementations. Addition with 13354-0.0 is also sufficient provided that the rounding mode is not -Infinity. 13355 13356``@llvm.canonicalize`` must preserve the equality relation. That is: 13357 13358- ``(@llvm.canonicalize(x) == x)`` is equivalent to ``(x == x)`` 13359- ``(@llvm.canonicalize(x) == @llvm.canonicalize(y))`` is equivalent to 13360 to ``(x == y)`` 13361 13362Additionally, the sign of zero must be conserved: 13363``@llvm.canonicalize(-0.0) = -0.0`` and ``@llvm.canonicalize(+0.0) = +0.0`` 13364 13365The payload bits of a NaN must be conserved, with two exceptions. 13366First, environments which use only a single canonical representation of NaN 13367must perform said canonicalization. Second, SNaNs must be quieted per the 13368usual methods. 13369 13370The canonicalization operation may be optimized away if: 13371 13372- The input is known to be canonical. For example, it was produced by a 13373 floating-point operation that is required by the standard to be canonical. 13374- The result is consumed only by (or fused with) other floating-point 13375 operations. That is, the bits of the floating-point value are not examined. 13376 13377'``llvm.fmuladd.*``' Intrinsic 13378^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13379 13380Syntax: 13381""""""" 13382 13383:: 13384 13385 declare float @llvm.fmuladd.f32(float %a, float %b, float %c) 13386 declare double @llvm.fmuladd.f64(double %a, double %b, double %c) 13387 13388Overview: 13389""""""""" 13390 13391The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add 13392expressions that can be fused if the code generator determines that (a) the 13393target instruction set has support for a fused operation, and (b) that the 13394fused operation is more efficient than the equivalent, separate pair of mul 13395and add instructions. 13396 13397Arguments: 13398"""""""""" 13399 13400The '``llvm.fmuladd.*``' intrinsics each take three arguments: two 13401multiplicands, a and b, and an addend c. 13402 13403Semantics: 13404"""""""""" 13405 13406The expression: 13407 13408:: 13409 13410 %0 = call float @llvm.fmuladd.f32(%a, %b, %c) 13411 13412is equivalent to the expression a \* b + c, except that rounding will 13413not be performed between the multiplication and addition steps if the 13414code generator fuses the operations. Fusion is not guaranteed, even if 13415the target platform supports it. If a fused multiply-add is required the 13416corresponding llvm.fma.\* intrinsic function should be used 13417instead. This never sets errno, just as '``llvm.fma.*``'. 13418 13419Examples: 13420""""""""" 13421 13422.. code-block:: llvm 13423 13424 %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c 13425 13426 13427Experimental Vector Reduction Intrinsics 13428---------------------------------------- 13429 13430Horizontal reductions of vectors can be expressed using the following 13431intrinsics. Each one takes a vector operand as an input and applies its 13432respective operation across all elements of the vector, returning a single 13433scalar result of the same element type. 13434 13435 13436'``llvm.experimental.vector.reduce.add.*``' Intrinsic 13437^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13438 13439Syntax: 13440""""""" 13441 13442:: 13443 13444 declare i32 @llvm.experimental.vector.reduce.add.i32.v4i32(<4 x i32> %a) 13445 declare i64 @llvm.experimental.vector.reduce.add.i64.v2i64(<2 x i64> %a) 13446 13447Overview: 13448""""""""" 13449 13450The '``llvm.experimental.vector.reduce.add.*``' intrinsics do an integer ``ADD`` 13451reduction of a vector, returning the result as a scalar. The return type matches 13452the element-type of the vector input. 13453 13454Arguments: 13455"""""""""" 13456The argument to this intrinsic must be a vector of integer values. 13457 13458'``llvm.experimental.vector.reduce.fadd.*``' Intrinsic 13459^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13460 13461Syntax: 13462""""""" 13463 13464:: 13465 13466 declare float @llvm.experimental.vector.reduce.fadd.f32.v4f32(float %acc, <4 x float> %a) 13467 declare double @llvm.experimental.vector.reduce.fadd.f64.v2f64(double %acc, <2 x double> %a) 13468 13469Overview: 13470""""""""" 13471 13472The '``llvm.experimental.vector.reduce.fadd.*``' intrinsics do a floating-point 13473``ADD`` reduction of a vector, returning the result as a scalar. The return type 13474matches the element-type of the vector input. 13475 13476If the intrinsic call has fast-math flags, then the reduction will not preserve 13477the associativity of an equivalent scalarized counterpart. If it does not have 13478fast-math flags, then the reduction will be *ordered*, implying that the 13479operation respects the associativity of a scalarized reduction. 13480 13481 13482Arguments: 13483"""""""""" 13484The first argument to this intrinsic is a scalar accumulator value, which is 13485only used when there are no fast-math flags attached. This argument may be undef 13486when fast-math flags are used. 13487 13488The second argument must be a vector of floating-point values. 13489 13490Examples: 13491""""""""" 13492 13493.. code-block:: llvm 13494 13495 %fast = call fast float @llvm.experimental.vector.reduce.fadd.f32.v4f32(float undef, <4 x float> %input) ; fast reduction 13496 %ord = call float @llvm.experimental.vector.reduce.fadd.f32.v4f32(float %acc, <4 x float> %input) ; ordered reduction 13497 13498 13499'``llvm.experimental.vector.reduce.mul.*``' Intrinsic 13500^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13501 13502Syntax: 13503""""""" 13504 13505:: 13506 13507 declare i32 @llvm.experimental.vector.reduce.mul.i32.v4i32(<4 x i32> %a) 13508 declare i64 @llvm.experimental.vector.reduce.mul.i64.v2i64(<2 x i64> %a) 13509 13510Overview: 13511""""""""" 13512 13513The '``llvm.experimental.vector.reduce.mul.*``' intrinsics do an integer ``MUL`` 13514reduction of a vector, returning the result as a scalar. The return type matches 13515the element-type of the vector input. 13516 13517Arguments: 13518"""""""""" 13519The argument to this intrinsic must be a vector of integer values. 13520 13521'``llvm.experimental.vector.reduce.fmul.*``' Intrinsic 13522^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13523 13524Syntax: 13525""""""" 13526 13527:: 13528 13529 declare float @llvm.experimental.vector.reduce.fmul.f32.v4f32(float %acc, <4 x float> %a) 13530 declare double @llvm.experimental.vector.reduce.fmul.f64.v2f64(double %acc, <2 x double> %a) 13531 13532Overview: 13533""""""""" 13534 13535The '``llvm.experimental.vector.reduce.fmul.*``' intrinsics do a floating-point 13536``MUL`` reduction of a vector, returning the result as a scalar. The return type 13537matches the element-type of the vector input. 13538 13539If the intrinsic call has fast-math flags, then the reduction will not preserve 13540the associativity of an equivalent scalarized counterpart. If it does not have 13541fast-math flags, then the reduction will be *ordered*, implying that the 13542operation respects the associativity of a scalarized reduction. 13543 13544 13545Arguments: 13546"""""""""" 13547The first argument to this intrinsic is a scalar accumulator value, which is 13548only used when there are no fast-math flags attached. This argument may be undef 13549when fast-math flags are used. 13550 13551The second argument must be a vector of floating-point values. 13552 13553Examples: 13554""""""""" 13555 13556.. code-block:: llvm 13557 13558 %fast = call fast float @llvm.experimental.vector.reduce.fmul.f32.v4f32(float undef, <4 x float> %input) ; fast reduction 13559 %ord = call float @llvm.experimental.vector.reduce.fmul.f32.v4f32(float %acc, <4 x float> %input) ; ordered reduction 13560 13561'``llvm.experimental.vector.reduce.and.*``' Intrinsic 13562^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13563 13564Syntax: 13565""""""" 13566 13567:: 13568 13569 declare i32 @llvm.experimental.vector.reduce.and.i32.v4i32(<4 x i32> %a) 13570 13571Overview: 13572""""""""" 13573 13574The '``llvm.experimental.vector.reduce.and.*``' intrinsics do a bitwise ``AND`` 13575reduction of a vector, returning the result as a scalar. The return type matches 13576the element-type of the vector input. 13577 13578Arguments: 13579"""""""""" 13580The argument to this intrinsic must be a vector of integer values. 13581 13582'``llvm.experimental.vector.reduce.or.*``' Intrinsic 13583^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13584 13585Syntax: 13586""""""" 13587 13588:: 13589 13590 declare i32 @llvm.experimental.vector.reduce.or.i32.v4i32(<4 x i32> %a) 13591 13592Overview: 13593""""""""" 13594 13595The '``llvm.experimental.vector.reduce.or.*``' intrinsics do a bitwise ``OR`` reduction 13596of a vector, returning the result as a scalar. The return type matches the 13597element-type of the vector input. 13598 13599Arguments: 13600"""""""""" 13601The argument to this intrinsic must be a vector of integer values. 13602 13603'``llvm.experimental.vector.reduce.xor.*``' Intrinsic 13604^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13605 13606Syntax: 13607""""""" 13608 13609:: 13610 13611 declare i32 @llvm.experimental.vector.reduce.xor.i32.v4i32(<4 x i32> %a) 13612 13613Overview: 13614""""""""" 13615 13616The '``llvm.experimental.vector.reduce.xor.*``' intrinsics do a bitwise ``XOR`` 13617reduction of a vector, returning the result as a scalar. The return type matches 13618the element-type of the vector input. 13619 13620Arguments: 13621"""""""""" 13622The argument to this intrinsic must be a vector of integer values. 13623 13624'``llvm.experimental.vector.reduce.smax.*``' Intrinsic 13625^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13626 13627Syntax: 13628""""""" 13629 13630:: 13631 13632 declare i32 @llvm.experimental.vector.reduce.smax.i32.v4i32(<4 x i32> %a) 13633 13634Overview: 13635""""""""" 13636 13637The '``llvm.experimental.vector.reduce.smax.*``' intrinsics do a signed integer 13638``MAX`` reduction of a vector, returning the result as a scalar. The return type 13639matches the element-type of the vector input. 13640 13641Arguments: 13642"""""""""" 13643The argument to this intrinsic must be a vector of integer values. 13644 13645'``llvm.experimental.vector.reduce.smin.*``' Intrinsic 13646^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13647 13648Syntax: 13649""""""" 13650 13651:: 13652 13653 declare i32 @llvm.experimental.vector.reduce.smin.i32.v4i32(<4 x i32> %a) 13654 13655Overview: 13656""""""""" 13657 13658The '``llvm.experimental.vector.reduce.smin.*``' intrinsics do a signed integer 13659``MIN`` reduction of a vector, returning the result as a scalar. The return type 13660matches the element-type of the vector input. 13661 13662Arguments: 13663"""""""""" 13664The argument to this intrinsic must be a vector of integer values. 13665 13666'``llvm.experimental.vector.reduce.umax.*``' Intrinsic 13667^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13668 13669Syntax: 13670""""""" 13671 13672:: 13673 13674 declare i32 @llvm.experimental.vector.reduce.umax.i32.v4i32(<4 x i32> %a) 13675 13676Overview: 13677""""""""" 13678 13679The '``llvm.experimental.vector.reduce.umax.*``' intrinsics do an unsigned 13680integer ``MAX`` reduction of a vector, returning the result as a scalar. The 13681return type matches the element-type of the vector input. 13682 13683Arguments: 13684"""""""""" 13685The argument to this intrinsic must be a vector of integer values. 13686 13687'``llvm.experimental.vector.reduce.umin.*``' Intrinsic 13688^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13689 13690Syntax: 13691""""""" 13692 13693:: 13694 13695 declare i32 @llvm.experimental.vector.reduce.umin.i32.v4i32(<4 x i32> %a) 13696 13697Overview: 13698""""""""" 13699 13700The '``llvm.experimental.vector.reduce.umin.*``' intrinsics do an unsigned 13701integer ``MIN`` reduction of a vector, returning the result as a scalar. The 13702return type matches the element-type of the vector input. 13703 13704Arguments: 13705"""""""""" 13706The argument to this intrinsic must be a vector of integer values. 13707 13708'``llvm.experimental.vector.reduce.fmax.*``' Intrinsic 13709^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13710 13711Syntax: 13712""""""" 13713 13714:: 13715 13716 declare float @llvm.experimental.vector.reduce.fmax.f32.v4f32(<4 x float> %a) 13717 declare double @llvm.experimental.vector.reduce.fmax.f64.v2f64(<2 x double> %a) 13718 13719Overview: 13720""""""""" 13721 13722The '``llvm.experimental.vector.reduce.fmax.*``' intrinsics do a floating-point 13723``MAX`` reduction of a vector, returning the result as a scalar. The return type 13724matches the element-type of the vector input. 13725 13726If the intrinsic call has the ``nnan`` fast-math flag then the operation can 13727assume that NaNs are not present in the input vector. 13728 13729Arguments: 13730"""""""""" 13731The argument to this intrinsic must be a vector of floating-point values. 13732 13733'``llvm.experimental.vector.reduce.fmin.*``' Intrinsic 13734^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13735 13736Syntax: 13737""""""" 13738 13739:: 13740 13741 declare float @llvm.experimental.vector.reduce.fmin.f32.v4f32(<4 x float> %a) 13742 declare double @llvm.experimental.vector.reduce.fmin.f64.v2f64(<2 x double> %a) 13743 13744Overview: 13745""""""""" 13746 13747The '``llvm.experimental.vector.reduce.fmin.*``' intrinsics do a floating-point 13748``MIN`` reduction of a vector, returning the result as a scalar. The return type 13749matches the element-type of the vector input. 13750 13751If the intrinsic call has the ``nnan`` fast-math flag then the operation can 13752assume that NaNs are not present in the input vector. 13753 13754Arguments: 13755"""""""""" 13756The argument to this intrinsic must be a vector of floating-point values. 13757 13758Half Precision Floating-Point Intrinsics 13759---------------------------------------- 13760 13761For most target platforms, half precision floating-point is a 13762storage-only format. This means that it is a dense encoding (in memory) 13763but does not support computation in the format. 13764 13765This means that code must first load the half-precision floating-point 13766value as an i16, then convert it to float with 13767:ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can 13768then be performed on the float value (including extending to double 13769etc). To store the value back to memory, it is first converted to float 13770if needed, then converted to i16 with 13771:ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an 13772i16 value. 13773 13774.. _int_convert_to_fp16: 13775 13776'``llvm.convert.to.fp16``' Intrinsic 13777^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13778 13779Syntax: 13780""""""" 13781 13782:: 13783 13784 declare i16 @llvm.convert.to.fp16.f32(float %a) 13785 declare i16 @llvm.convert.to.fp16.f64(double %a) 13786 13787Overview: 13788""""""""" 13789 13790The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a 13791conventional floating-point type to half precision floating-point format. 13792 13793Arguments: 13794"""""""""" 13795 13796The intrinsic function contains single argument - the value to be 13797converted. 13798 13799Semantics: 13800"""""""""" 13801 13802The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a 13803conventional floating-point format to half precision floating-point format. The 13804return value is an ``i16`` which contains the converted number. 13805 13806Examples: 13807""""""""" 13808 13809.. code-block:: llvm 13810 13811 %res = call i16 @llvm.convert.to.fp16.f32(float %a) 13812 store i16 %res, i16* @x, align 2 13813 13814.. _int_convert_from_fp16: 13815 13816'``llvm.convert.from.fp16``' Intrinsic 13817^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13818 13819Syntax: 13820""""""" 13821 13822:: 13823 13824 declare float @llvm.convert.from.fp16.f32(i16 %a) 13825 declare double @llvm.convert.from.fp16.f64(i16 %a) 13826 13827Overview: 13828""""""""" 13829 13830The '``llvm.convert.from.fp16``' intrinsic function performs a 13831conversion from half precision floating-point format to single precision 13832floating-point format. 13833 13834Arguments: 13835"""""""""" 13836 13837The intrinsic function contains single argument - the value to be 13838converted. 13839 13840Semantics: 13841"""""""""" 13842 13843The '``llvm.convert.from.fp16``' intrinsic function performs a 13844conversion from half single precision floating-point format to single 13845precision floating-point format. The input half-float value is 13846represented by an ``i16`` value. 13847 13848Examples: 13849""""""""" 13850 13851.. code-block:: llvm 13852 13853 %a = load i16, i16* @x, align 2 13854 %res = call float @llvm.convert.from.fp16(i16 %a) 13855 13856.. _dbg_intrinsics: 13857 13858Debugger Intrinsics 13859------------------- 13860 13861The LLVM debugger intrinsics (which all start with ``llvm.dbg.`` 13862prefix), are described in the `LLVM Source Level 13863Debugging <SourceLevelDebugging.html#format-common-intrinsics>`_ 13864document. 13865 13866Exception Handling Intrinsics 13867----------------------------- 13868 13869The LLVM exception handling intrinsics (which all start with 13870``llvm.eh.`` prefix), are described in the `LLVM Exception 13871Handling <ExceptionHandling.html#format-common-intrinsics>`_ document. 13872 13873.. _int_trampoline: 13874 13875Trampoline Intrinsics 13876--------------------- 13877 13878These intrinsics make it possible to excise one parameter, marked with 13879the :ref:`nest <nest>` attribute, from a function. The result is a 13880callable function pointer lacking the nest parameter - the caller does 13881not need to provide a value for it. Instead, the value to use is stored 13882in advance in a "trampoline", a block of memory usually allocated on the 13883stack, which also contains code to splice the nest value into the 13884argument list. This is used to implement the GCC nested function address 13885extension. 13886 13887For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)`` 13888then the resulting function pointer has signature ``i32 (i32, i32)*``. 13889It can be created as follows: 13890 13891.. code-block:: llvm 13892 13893 %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 13894 %tramp1 = getelementptr [10 x i8], [10 x i8]* %tramp, i32 0, i32 0 13895 call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval) 13896 %p = call i8* @llvm.adjust.trampoline(i8* %tramp1) 13897 %fp = bitcast i8* %p to i32 (i32, i32)* 13898 13899The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to 13900``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``. 13901 13902.. _int_it: 13903 13904'``llvm.init.trampoline``' Intrinsic 13905^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13906 13907Syntax: 13908""""""" 13909 13910:: 13911 13912 declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) 13913 13914Overview: 13915""""""""" 13916 13917This fills the memory pointed to by ``tramp`` with executable code, 13918turning it into a trampoline. 13919 13920Arguments: 13921"""""""""" 13922 13923The ``llvm.init.trampoline`` intrinsic takes three arguments, all 13924pointers. The ``tramp`` argument must point to a sufficiently large and 13925sufficiently aligned block of memory; this memory is written to by the 13926intrinsic. Note that the size and the alignment are target-specific - 13927LLVM currently provides no portable way of determining them, so a 13928front-end that generates this intrinsic needs to have some 13929target-specific knowledge. The ``func`` argument must hold a function 13930bitcast to an ``i8*``. 13931 13932Semantics: 13933"""""""""" 13934 13935The block of memory pointed to by ``tramp`` is filled with target 13936dependent code, turning it into a function. Then ``tramp`` needs to be 13937passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can 13938be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new 13939function's signature is the same as that of ``func`` with any arguments 13940marked with the ``nest`` attribute removed. At most one such ``nest`` 13941argument is allowed, and it must be of pointer type. Calling the new 13942function is equivalent to calling ``func`` with the same argument list, 13943but with ``nval`` used for the missing ``nest`` argument. If, after 13944calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is 13945modified, then the effect of any later call to the returned function 13946pointer is undefined. 13947 13948.. _int_at: 13949 13950'``llvm.adjust.trampoline``' Intrinsic 13951^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13952 13953Syntax: 13954""""""" 13955 13956:: 13957 13958 declare i8* @llvm.adjust.trampoline(i8* <tramp>) 13959 13960Overview: 13961""""""""" 13962 13963This performs any required machine-specific adjustment to the address of 13964a trampoline (passed as ``tramp``). 13965 13966Arguments: 13967"""""""""" 13968 13969``tramp`` must point to a block of memory which already has trampoline 13970code filled in by a previous call to 13971:ref:`llvm.init.trampoline <int_it>`. 13972 13973Semantics: 13974"""""""""" 13975 13976On some architectures the address of the code to be executed needs to be 13977different than the address where the trampoline is actually stored. This 13978intrinsic returns the executable address corresponding to ``tramp`` 13979after performing the required machine specific adjustments. The pointer 13980returned can then be :ref:`bitcast and executed <int_trampoline>`. 13981 13982.. _int_mload_mstore: 13983 13984Masked Vector Load and Store Intrinsics 13985--------------------------------------- 13986 13987LLVM provides intrinsics for predicated vector load and store operations. The predicate is specified by a mask operand, which holds one bit per vector element, switching the associated vector lane on or off. The memory addresses corresponding to the "off" lanes are not accessed. When all bits of the mask are on, the intrinsic is identical to a regular vector load or store. When all bits are off, no memory is accessed. 13988 13989.. _int_mload: 13990 13991'``llvm.masked.load.*``' Intrinsics 13992^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13993 13994Syntax: 13995""""""" 13996This is an overloaded intrinsic. The loaded data is a vector of any integer, floating-point or pointer data type. 13997 13998:: 13999 14000 declare <16 x float> @llvm.masked.load.v16f32.p0v16f32 (<16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>) 14001 declare <2 x double> @llvm.masked.load.v2f64.p0v2f64 (<2 x double>* <ptr>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>) 14002 ;; The data is a vector of pointers to double 14003 declare <8 x double*> @llvm.masked.load.v8p0f64.p0v8p0f64 (<8 x double*>* <ptr>, i32 <alignment>, <8 x i1> <mask>, <8 x double*> <passthru>) 14004 ;; The data is a vector of function pointers 14005 declare <8 x i32 ()*> @llvm.masked.load.v8p0f_i32f.p0v8p0f_i32f (<8 x i32 ()*>* <ptr>, i32 <alignment>, <8 x i1> <mask>, <8 x i32 ()*> <passthru>) 14006 14007Overview: 14008""""""""" 14009 14010Reads a vector from memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. The masked-off lanes in the result vector are taken from the corresponding lanes of the '``passthru``' operand. 14011 14012 14013Arguments: 14014"""""""""" 14015 14016The first operand is the base pointer for the load. The second operand is the alignment of the source location. It must be a constant integer value. The third operand, mask, is a vector of boolean values with the same number of elements as the return type. The fourth is a pass-through value that is used to fill the masked-off lanes of the result. The return type, underlying type of the base pointer and the type of the '``passthru``' operand are the same vector types. 14017 14018 14019Semantics: 14020"""""""""" 14021 14022The '``llvm.masked.load``' intrinsic is designed for conditional reading of selected vector elements in a single IR operation. It is useful for targets that support vector masked loads and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar load operations. 14023The result of this operation is equivalent to a regular vector load instruction followed by a 'select' between the loaded and the passthru values, predicated on the same mask. However, using this intrinsic prevents exceptions on memory access to masked-off lanes. 14024 14025 14026:: 14027 14028 %res = call <16 x float> @llvm.masked.load.v16f32.p0v16f32 (<16 x float>* %ptr, i32 4, <16 x i1>%mask, <16 x float> %passthru) 14029 14030 ;; The result of the two following instructions is identical aside from potential memory access exception 14031 %loadlal = load <16 x float>, <16 x float>* %ptr, align 4 14032 %res = select <16 x i1> %mask, <16 x float> %loadlal, <16 x float> %passthru 14033 14034.. _int_mstore: 14035 14036'``llvm.masked.store.*``' Intrinsics 14037^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14038 14039Syntax: 14040""""""" 14041This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type. 14042 14043:: 14044 14045 declare void @llvm.masked.store.v8i32.p0v8i32 (<8 x i32> <value>, <8 x i32>* <ptr>, i32 <alignment>, <8 x i1> <mask>) 14046 declare void @llvm.masked.store.v16f32.p0v16f32 (<16 x float> <value>, <16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>) 14047 ;; The data is a vector of pointers to double 14048 declare void @llvm.masked.store.v8p0f64.p0v8p0f64 (<8 x double*> <value>, <8 x double*>* <ptr>, i32 <alignment>, <8 x i1> <mask>) 14049 ;; The data is a vector of function pointers 14050 declare void @llvm.masked.store.v4p0f_i32f.p0v4p0f_i32f (<4 x i32 ()*> <value>, <4 x i32 ()*>* <ptr>, i32 <alignment>, <4 x i1> <mask>) 14051 14052Overview: 14053""""""""" 14054 14055Writes a vector to memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. 14056 14057Arguments: 14058"""""""""" 14059 14060The first operand is the vector value to be written to memory. The second operand is the base pointer for the store, it has the same underlying type as the value operand. The third operand is the alignment of the destination location. The fourth operand, mask, is a vector of boolean values. The types of the mask and the value operand must have the same number of vector elements. 14061 14062 14063Semantics: 14064"""""""""" 14065 14066The '``llvm.masked.store``' intrinsics is designed for conditional writing of selected vector elements in a single IR operation. It is useful for targets that support vector masked store and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations. 14067The result of this operation is equivalent to a load-modify-store sequence. However, using this intrinsic prevents exceptions and data races on memory access to masked-off lanes. 14068 14069:: 14070 14071 call void @llvm.masked.store.v16f32.p0v16f32(<16 x float> %value, <16 x float>* %ptr, i32 4, <16 x i1> %mask) 14072 14073 ;; The result of the following instructions is identical aside from potential data races and memory access exceptions 14074 %oldval = load <16 x float>, <16 x float>* %ptr, align 4 14075 %res = select <16 x i1> %mask, <16 x float> %value, <16 x float> %oldval 14076 store <16 x float> %res, <16 x float>* %ptr, align 4 14077 14078 14079Masked Vector Gather and Scatter Intrinsics 14080------------------------------------------- 14081 14082LLVM provides intrinsics for vector gather and scatter operations. They are similar to :ref:`Masked Vector Load and Store <int_mload_mstore>`, except they are designed for arbitrary memory accesses, rather than sequential memory accesses. Gather and scatter also employ a mask operand, which holds one bit per vector element, switching the associated vector lane on or off. The memory addresses corresponding to the "off" lanes are not accessed. When all bits are off, no memory is accessed. 14083 14084.. _int_mgather: 14085 14086'``llvm.masked.gather.*``' Intrinsics 14087^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14088 14089Syntax: 14090""""""" 14091This is an overloaded intrinsic. The loaded data are multiple scalar values of any integer, floating-point or pointer data type gathered together into one vector. 14092 14093:: 14094 14095 declare <16 x float> @llvm.masked.gather.v16f32.v16p0f32 (<16 x float*> <ptrs>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>) 14096 declare <2 x double> @llvm.masked.gather.v2f64.v2p1f64 (<2 x double addrspace(1)*> <ptrs>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>) 14097 declare <8 x float*> @llvm.masked.gather.v8p0f32.v8p0p0f32 (<8 x float**> <ptrs>, i32 <alignment>, <8 x i1> <mask>, <8 x float*> <passthru>) 14098 14099Overview: 14100""""""""" 14101 14102Reads scalar values from arbitrary memory locations and gathers them into one vector. The memory locations are provided in the vector of pointers '``ptrs``'. The memory is accessed according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. The masked-off lanes in the result vector are taken from the corresponding lanes of the '``passthru``' operand. 14103 14104 14105Arguments: 14106"""""""""" 14107 14108The first operand is a vector of pointers which holds all memory addresses to read. The second operand is an alignment of the source addresses. It must be a constant integer value. The third operand, mask, is a vector of boolean values with the same number of elements as the return type. The fourth is a pass-through value that is used to fill the masked-off lanes of the result. The return type, underlying type of the vector of pointers and the type of the '``passthru``' operand are the same vector types. 14109 14110 14111Semantics: 14112"""""""""" 14113 14114The '``llvm.masked.gather``' intrinsic is designed for conditional reading of multiple scalar values from arbitrary memory locations in a single IR operation. It is useful for targets that support vector masked gathers and allows vectorizing basic blocks with data and control divergence. Other targets may support this intrinsic differently, for example by lowering it into a sequence of scalar load operations. 14115The semantics of this operation are equivalent to a sequence of conditional scalar loads with subsequent gathering all loaded values into a single vector. The mask restricts memory access to certain lanes and facilitates vectorization of predicated basic blocks. 14116 14117 14118:: 14119 14120 %res = call <4 x double> @llvm.masked.gather.v4f64.v4p0f64 (<4 x double*> %ptrs, i32 8, <4 x i1> <i1 true, i1 true, i1 true, i1 true>, <4 x double> undef) 14121 14122 ;; The gather with all-true mask is equivalent to the following instruction sequence 14123 %ptr0 = extractelement <4 x double*> %ptrs, i32 0 14124 %ptr1 = extractelement <4 x double*> %ptrs, i32 1 14125 %ptr2 = extractelement <4 x double*> %ptrs, i32 2 14126 %ptr3 = extractelement <4 x double*> %ptrs, i32 3 14127 14128 %val0 = load double, double* %ptr0, align 8 14129 %val1 = load double, double* %ptr1, align 8 14130 %val2 = load double, double* %ptr2, align 8 14131 %val3 = load double, double* %ptr3, align 8 14132 14133 %vec0 = insertelement <4 x double>undef, %val0, 0 14134 %vec01 = insertelement <4 x double>%vec0, %val1, 1 14135 %vec012 = insertelement <4 x double>%vec01, %val2, 2 14136 %vec0123 = insertelement <4 x double>%vec012, %val3, 3 14137 14138.. _int_mscatter: 14139 14140'``llvm.masked.scatter.*``' Intrinsics 14141^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14142 14143Syntax: 14144""""""" 14145This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type. Each vector element is stored in an arbitrary memory address. Scatter with overlapping addresses is guaranteed to be ordered from least-significant to most-significant element. 14146 14147:: 14148 14149 declare void @llvm.masked.scatter.v8i32.v8p0i32 (<8 x i32> <value>, <8 x i32*> <ptrs>, i32 <alignment>, <8 x i1> <mask>) 14150 declare void @llvm.masked.scatter.v16f32.v16p1f32 (<16 x float> <value>, <16 x float addrspace(1)*> <ptrs>, i32 <alignment>, <16 x i1> <mask>) 14151 declare void @llvm.masked.scatter.v4p0f64.v4p0p0f64 (<4 x double*> <value>, <4 x double**> <ptrs>, i32 <alignment>, <4 x i1> <mask>) 14152 14153Overview: 14154""""""""" 14155 14156Writes each element from the value vector to the corresponding memory address. The memory addresses are represented as a vector of pointers. Writing is done according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. 14157 14158Arguments: 14159"""""""""" 14160 14161The first operand is a vector value to be written to memory. The second operand is a vector of pointers, pointing to where the value elements should be stored. It has the same underlying type as the value operand. The third operand is an alignment of the destination addresses. The fourth operand, mask, is a vector of boolean values. The types of the mask and the value operand must have the same number of vector elements. 14162 14163 14164Semantics: 14165"""""""""" 14166 14167The '``llvm.masked.scatter``' intrinsics is designed for writing selected vector elements to arbitrary memory addresses in a single IR operation. The operation may be conditional, when not all bits in the mask are switched on. It is useful for targets that support vector masked scatter and allows vectorizing basic blocks with data and control divergence. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations. 14168 14169:: 14170 14171 ;; This instruction unconditionally stores data vector in multiple addresses 14172 call @llvm.masked.scatter.v8i32.v8p0i32 (<8 x i32> %value, <8 x i32*> %ptrs, i32 4, <8 x i1> <true, true, .. true>) 14173 14174 ;; It is equivalent to a list of scalar stores 14175 %val0 = extractelement <8 x i32> %value, i32 0 14176 %val1 = extractelement <8 x i32> %value, i32 1 14177 .. 14178 %val7 = extractelement <8 x i32> %value, i32 7 14179 %ptr0 = extractelement <8 x i32*> %ptrs, i32 0 14180 %ptr1 = extractelement <8 x i32*> %ptrs, i32 1 14181 .. 14182 %ptr7 = extractelement <8 x i32*> %ptrs, i32 7 14183 ;; Note: the order of the following stores is important when they overlap: 14184 store i32 %val0, i32* %ptr0, align 4 14185 store i32 %val1, i32* %ptr1, align 4 14186 .. 14187 store i32 %val7, i32* %ptr7, align 4 14188 14189 14190Masked Vector Expanding Load and Compressing Store Intrinsics 14191------------------------------------------------------------- 14192 14193LLVM provides intrinsics for expanding load and compressing store operations. Data selected from a vector according to a mask is stored in consecutive memory addresses (compressed store), and vice-versa (expanding load). These operations effective map to "if (cond.i) a[j++] = v.i" and "if (cond.i) v.i = a[j++]" patterns, respectively. Note that when the mask starts with '1' bits followed by '0' bits, these operations are identical to :ref:`llvm.masked.store <int_mstore>` and :ref:`llvm.masked.load <int_mload>`. 14194 14195.. _int_expandload: 14196 14197'``llvm.masked.expandload.*``' Intrinsics 14198^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14199 14200Syntax: 14201""""""" 14202This is an overloaded intrinsic. Several values of integer, floating point or pointer data type are loaded from consecutive memory addresses and stored into the elements of a vector according to the mask. 14203 14204:: 14205 14206 declare <16 x float> @llvm.masked.expandload.v16f32 (float* <ptr>, <16 x i1> <mask>, <16 x float> <passthru>) 14207 declare <2 x i64> @llvm.masked.expandload.v2i64 (i64* <ptr>, <2 x i1> <mask>, <2 x i64> <passthru>) 14208 14209Overview: 14210""""""""" 14211 14212Reads a number of scalar values sequentially from memory location provided in '``ptr``' and spreads them in a vector. The '``mask``' holds a bit for each vector lane. The number of elements read from memory is equal to the number of '1' bits in the mask. The loaded elements are positioned in the destination vector according to the sequence of '1' and '0' bits in the mask. E.g., if the mask vector is '10010001', "explandload" reads 3 values from memory addresses ptr, ptr+1, ptr+2 and places them in lanes 0, 3 and 7 accordingly. The masked-off lanes are filled by elements from the corresponding lanes of the '``passthru``' operand. 14213 14214 14215Arguments: 14216"""""""""" 14217 14218The first operand is the base pointer for the load. It has the same underlying type as the element of the returned vector. The second operand, mask, is a vector of boolean values with the same number of elements as the return type. The third is a pass-through value that is used to fill the masked-off lanes of the result. The return type and the type of the '``passthru``' operand have the same vector type. 14219 14220Semantics: 14221"""""""""" 14222 14223The '``llvm.masked.expandload``' intrinsic is designed for reading multiple scalar values from adjacent memory addresses into possibly non-adjacent vector lanes. It is useful for targets that support vector expanding loads and allows vectorizing loop with cross-iteration dependency like in the following example: 14224 14225.. code-block:: c 14226 14227 // In this loop we load from B and spread the elements into array A. 14228 double *A, B; int *C; 14229 for (int i = 0; i < size; ++i) { 14230 if (C[i] != 0) 14231 A[i] = B[j++]; 14232 } 14233 14234 14235.. code-block:: llvm 14236 14237 ; Load several elements from array B and expand them in a vector. 14238 ; The number of loaded elements is equal to the number of '1' elements in the Mask. 14239 %Tmp = call <8 x double> @llvm.masked.expandload.v8f64(double* %Bptr, <8 x i1> %Mask, <8 x double> undef) 14240 ; Store the result in A 14241 call void @llvm.masked.store.v8f64.p0v8f64(<8 x double> %Tmp, <8 x double>* %Aptr, i32 8, <8 x i1> %Mask) 14242 14243 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask. 14244 %MaskI = bitcast <8 x i1> %Mask to i8 14245 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI) 14246 %MaskI64 = zext i8 %MaskIPopcnt to i64 14247 %BNextInd = add i64 %BInd, %MaskI64 14248 14249 14250Other targets may support this intrinsic differently, for example, by lowering it into a sequence of conditional scalar load operations and shuffles. 14251If all mask elements are '1', the intrinsic behavior is equivalent to the regular unmasked vector load. 14252 14253.. _int_compressstore: 14254 14255'``llvm.masked.compressstore.*``' Intrinsics 14256^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14257 14258Syntax: 14259""""""" 14260This is an overloaded intrinsic. A number of scalar values of integer, floating point or pointer data type are collected from an input vector and stored into adjacent memory addresses. A mask defines which elements to collect from the vector. 14261 14262:: 14263 14264 declare void @llvm.masked.compressstore.v8i32 (<8 x i32> <value>, i32* <ptr>, <8 x i1> <mask>) 14265 declare void @llvm.masked.compressstore.v16f32 (<16 x float> <value>, float* <ptr>, <16 x i1> <mask>) 14266 14267Overview: 14268""""""""" 14269 14270Selects elements from input vector '``value``' according to the '``mask``'. All selected elements are written into adjacent memory addresses starting at address '`ptr`', from lower to higher. The mask holds a bit for each vector lane, and is used to select elements to be stored. The number of elements to be stored is equal to the number of active bits in the mask. 14271 14272Arguments: 14273"""""""""" 14274 14275The first operand is the input vector, from which elements are collected and written to memory. The second operand is the base pointer for the store, it has the same underlying type as the element of the input vector operand. The third operand is the mask, a vector of boolean values. The mask and the input vector must have the same number of vector elements. 14276 14277 14278Semantics: 14279"""""""""" 14280 14281The '``llvm.masked.compressstore``' intrinsic is designed for compressing data in memory. It allows to collect elements from possibly non-adjacent lanes of a vector and store them contiguously in memory in one IR operation. It is useful for targets that support compressing store operations and allows vectorizing loops with cross-iteration dependences like in the following example: 14282 14283.. code-block:: c 14284 14285 // In this loop we load elements from A and store them consecutively in B 14286 double *A, B; int *C; 14287 for (int i = 0; i < size; ++i) { 14288 if (C[i] != 0) 14289 B[j++] = A[i] 14290 } 14291 14292 14293.. code-block:: llvm 14294 14295 ; Load elements from A. 14296 %Tmp = call <8 x double> @llvm.masked.load.v8f64.p0v8f64(<8 x double>* %Aptr, i32 8, <8 x i1> %Mask, <8 x double> undef) 14297 ; Store all selected elements consecutively in array B 14298 call <void> @llvm.masked.compressstore.v8f64(<8 x double> %Tmp, double* %Bptr, <8 x i1> %Mask) 14299 14300 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask. 14301 %MaskI = bitcast <8 x i1> %Mask to i8 14302 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI) 14303 %MaskI64 = zext i8 %MaskIPopcnt to i64 14304 %BNextInd = add i64 %BInd, %MaskI64 14305 14306 14307Other targets may support this intrinsic differently, for example, by lowering it into a sequence of branches that guard scalar store operations. 14308 14309 14310Memory Use Markers 14311------------------ 14312 14313This class of intrinsics provides information about the lifetime of 14314memory objects and ranges where variables are immutable. 14315 14316.. _int_lifestart: 14317 14318'``llvm.lifetime.start``' Intrinsic 14319^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14320 14321Syntax: 14322""""""" 14323 14324:: 14325 14326 declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>) 14327 14328Overview: 14329""""""""" 14330 14331The '``llvm.lifetime.start``' intrinsic specifies the start of a memory 14332object's lifetime. 14333 14334Arguments: 14335"""""""""" 14336 14337The first argument is a constant integer representing the size of the 14338object, or -1 if it is variable sized. The second argument is a pointer 14339to the object. 14340 14341Semantics: 14342"""""""""" 14343 14344This intrinsic indicates that before this point in the code, the value 14345of the memory pointed to by ``ptr`` is dead. This means that it is known 14346to never be used and has an undefined value. A load from the pointer 14347that precedes this intrinsic can be replaced with ``'undef'``. 14348 14349.. _int_lifeend: 14350 14351'``llvm.lifetime.end``' Intrinsic 14352^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14353 14354Syntax: 14355""""""" 14356 14357:: 14358 14359 declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>) 14360 14361Overview: 14362""""""""" 14363 14364The '``llvm.lifetime.end``' intrinsic specifies the end of a memory 14365object's lifetime. 14366 14367Arguments: 14368"""""""""" 14369 14370The first argument is a constant integer representing the size of the 14371object, or -1 if it is variable sized. The second argument is a pointer 14372to the object. 14373 14374Semantics: 14375"""""""""" 14376 14377This intrinsic indicates that after this point in the code, the value of 14378the memory pointed to by ``ptr`` is dead. This means that it is known to 14379never be used and has an undefined value. Any stores into the memory 14380object following this intrinsic may be removed as dead. 14381 14382'``llvm.invariant.start``' Intrinsic 14383^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14384 14385Syntax: 14386""""""" 14387This is an overloaded intrinsic. The memory object can belong to any address space. 14388 14389:: 14390 14391 declare {}* @llvm.invariant.start.p0i8(i64 <size>, i8* nocapture <ptr>) 14392 14393Overview: 14394""""""""" 14395 14396The '``llvm.invariant.start``' intrinsic specifies that the contents of 14397a memory object will not change. 14398 14399Arguments: 14400"""""""""" 14401 14402The first argument is a constant integer representing the size of the 14403object, or -1 if it is variable sized. The second argument is a pointer 14404to the object. 14405 14406Semantics: 14407"""""""""" 14408 14409This intrinsic indicates that until an ``llvm.invariant.end`` that uses 14410the return value, the referenced memory location is constant and 14411unchanging. 14412 14413'``llvm.invariant.end``' Intrinsic 14414^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14415 14416Syntax: 14417""""""" 14418This is an overloaded intrinsic. The memory object can belong to any address space. 14419 14420:: 14421 14422 declare void @llvm.invariant.end.p0i8({}* <start>, i64 <size>, i8* nocapture <ptr>) 14423 14424Overview: 14425""""""""" 14426 14427The '``llvm.invariant.end``' intrinsic specifies that the contents of a 14428memory object are mutable. 14429 14430Arguments: 14431"""""""""" 14432 14433The first argument is the matching ``llvm.invariant.start`` intrinsic. 14434The second argument is a constant integer representing the size of the 14435object, or -1 if it is variable sized and the third argument is a 14436pointer to the object. 14437 14438Semantics: 14439"""""""""" 14440 14441This intrinsic indicates that the memory is mutable again. 14442 14443'``llvm.launder.invariant.group``' Intrinsic 14444^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14445 14446Syntax: 14447""""""" 14448This is an overloaded intrinsic. The memory object can belong to any address 14449space. The returned pointer must belong to the same address space as the 14450argument. 14451 14452:: 14453 14454 declare i8* @llvm.launder.invariant.group.p0i8(i8* <ptr>) 14455 14456Overview: 14457""""""""" 14458 14459The '``llvm.launder.invariant.group``' intrinsic can be used when an invariant 14460established by ``invariant.group`` metadata no longer holds, to obtain a new 14461pointer value that carries fresh invariant group information. It is an 14462experimental intrinsic, which means that its semantics might change in the 14463future. 14464 14465 14466Arguments: 14467"""""""""" 14468 14469The ``llvm.launder.invariant.group`` takes only one argument, which is a pointer 14470to the memory. 14471 14472Semantics: 14473"""""""""" 14474 14475Returns another pointer that aliases its argument but which is considered different 14476for the purposes of ``load``/``store`` ``invariant.group`` metadata. 14477It does not read any accessible memory and the execution can be speculated. 14478 14479'``llvm.strip.invariant.group``' Intrinsic 14480^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14481 14482Syntax: 14483""""""" 14484This is an overloaded intrinsic. The memory object can belong to any address 14485space. The returned pointer must belong to the same address space as the 14486argument. 14487 14488:: 14489 14490 declare i8* @llvm.strip.invariant.group.p0i8(i8* <ptr>) 14491 14492Overview: 14493""""""""" 14494 14495The '``llvm.strip.invariant.group``' intrinsic can be used when an invariant 14496established by ``invariant.group`` metadata no longer holds, to obtain a new pointer 14497value that does not carry the invariant information. It is an experimental 14498intrinsic, which means that its semantics might change in the future. 14499 14500 14501Arguments: 14502"""""""""" 14503 14504The ``llvm.strip.invariant.group`` takes only one argument, which is a pointer 14505to the memory. 14506 14507Semantics: 14508"""""""""" 14509 14510Returns another pointer that aliases its argument but which has no associated 14511``invariant.group`` metadata. 14512It does not read any memory and can be speculated. 14513 14514 14515 14516.. _constrainedfp: 14517 14518Constrained Floating-Point Intrinsics 14519------------------------------------- 14520 14521These intrinsics are used to provide special handling of floating-point 14522operations when specific rounding mode or floating-point exception behavior is 14523required. By default, LLVM optimization passes assume that the rounding mode is 14524round-to-nearest and that floating-point exceptions will not be monitored. 14525Constrained FP intrinsics are used to support non-default rounding modes and 14526accurately preserve exception behavior without compromising LLVM's ability to 14527optimize FP code when the default behavior is used. 14528 14529Each of these intrinsics corresponds to a normal floating-point operation. The 14530first two arguments and the return value are the same as the corresponding FP 14531operation. 14532 14533The third argument is a metadata argument specifying the rounding mode to be 14534assumed. This argument must be one of the following strings: 14535 14536:: 14537 14538 "round.dynamic" 14539 "round.tonearest" 14540 "round.downward" 14541 "round.upward" 14542 "round.towardzero" 14543 14544If this argument is "round.dynamic" optimization passes must assume that the 14545rounding mode is unknown and may change at runtime. No transformations that 14546depend on rounding mode may be performed in this case. 14547 14548The other possible values for the rounding mode argument correspond to the 14549similarly named IEEE rounding modes. If the argument is any of these values 14550optimization passes may perform transformations as long as they are consistent 14551with the specified rounding mode. 14552 14553For example, 'x-0'->'x' is not a valid transformation if the rounding mode is 14554"round.downward" or "round.dynamic" because if the value of 'x' is +0 then 14555'x-0' should evaluate to '-0' when rounding downward. However, this 14556transformation is legal for all other rounding modes. 14557 14558For values other than "round.dynamic" optimization passes may assume that the 14559actual runtime rounding mode (as defined in a target-specific manner) matches 14560the specified rounding mode, but this is not guaranteed. Using a specific 14561non-dynamic rounding mode which does not match the actual rounding mode at 14562runtime results in undefined behavior. 14563 14564The fourth argument to the constrained floating-point intrinsics specifies the 14565required exception behavior. This argument must be one of the following 14566strings: 14567 14568:: 14569 14570 "fpexcept.ignore" 14571 "fpexcept.maytrap" 14572 "fpexcept.strict" 14573 14574If this argument is "fpexcept.ignore" optimization passes may assume that the 14575exception status flags will not be read and that floating-point exceptions will 14576be masked. This allows transformations to be performed that may change the 14577exception semantics of the original code. For example, FP operations may be 14578speculatively executed in this case whereas they must not be for either of the 14579other possible values of this argument. 14580 14581If the exception behavior argument is "fpexcept.maytrap" optimization passes 14582must avoid transformations that may raise exceptions that would not have been 14583raised by the original code (such as speculatively executing FP operations), but 14584passes are not required to preserve all exceptions that are implied by the 14585original code. For example, exceptions may be potentially hidden by constant 14586folding. 14587 14588If the exception behavior argument is "fpexcept.strict" all transformations must 14589strictly preserve the floating-point exception semantics of the original code. 14590Any FP exception that would have been raised by the original code must be raised 14591by the transformed code, and the transformed code must not raise any FP 14592exceptions that would not have been raised by the original code. This is the 14593exception behavior argument that will be used if the code being compiled reads 14594the FP exception status flags, but this mode can also be used with code that 14595unmasks FP exceptions. 14596 14597The number and order of floating-point exceptions is NOT guaranteed. For 14598example, a series of FP operations that each may raise exceptions may be 14599vectorized into a single instruction that raises each unique exception a single 14600time. 14601 14602 14603'``llvm.experimental.constrained.fadd``' Intrinsic 14604^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14605 14606Syntax: 14607""""""" 14608 14609:: 14610 14611 declare <type> 14612 @llvm.experimental.constrained.fadd(<type> <op1>, <type> <op2>, 14613 metadata <rounding mode>, 14614 metadata <exception behavior>) 14615 14616Overview: 14617""""""""" 14618 14619The '``llvm.experimental.constrained.fadd``' intrinsic returns the sum of its 14620two operands. 14621 14622 14623Arguments: 14624"""""""""" 14625 14626The first two arguments to the '``llvm.experimental.constrained.fadd``' 14627intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 14628of floating-point values. Both arguments must have identical types. 14629 14630The third and fourth arguments specify the rounding mode and exception 14631behavior as described above. 14632 14633Semantics: 14634"""""""""" 14635 14636The value produced is the floating-point sum of the two value operands and has 14637the same type as the operands. 14638 14639 14640'``llvm.experimental.constrained.fsub``' Intrinsic 14641^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14642 14643Syntax: 14644""""""" 14645 14646:: 14647 14648 declare <type> 14649 @llvm.experimental.constrained.fsub(<type> <op1>, <type> <op2>, 14650 metadata <rounding mode>, 14651 metadata <exception behavior>) 14652 14653Overview: 14654""""""""" 14655 14656The '``llvm.experimental.constrained.fsub``' intrinsic returns the difference 14657of its two operands. 14658 14659 14660Arguments: 14661"""""""""" 14662 14663The first two arguments to the '``llvm.experimental.constrained.fsub``' 14664intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 14665of floating-point values. Both arguments must have identical types. 14666 14667The third and fourth arguments specify the rounding mode and exception 14668behavior as described above. 14669 14670Semantics: 14671"""""""""" 14672 14673The value produced is the floating-point difference of the two value operands 14674and has the same type as the operands. 14675 14676 14677'``llvm.experimental.constrained.fmul``' Intrinsic 14678^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14679 14680Syntax: 14681""""""" 14682 14683:: 14684 14685 declare <type> 14686 @llvm.experimental.constrained.fmul(<type> <op1>, <type> <op2>, 14687 metadata <rounding mode>, 14688 metadata <exception behavior>) 14689 14690Overview: 14691""""""""" 14692 14693The '``llvm.experimental.constrained.fmul``' intrinsic returns the product of 14694its two operands. 14695 14696 14697Arguments: 14698"""""""""" 14699 14700The first two arguments to the '``llvm.experimental.constrained.fmul``' 14701intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 14702of floating-point values. Both arguments must have identical types. 14703 14704The third and fourth arguments specify the rounding mode and exception 14705behavior as described above. 14706 14707Semantics: 14708"""""""""" 14709 14710The value produced is the floating-point product of the two value operands and 14711has the same type as the operands. 14712 14713 14714'``llvm.experimental.constrained.fdiv``' Intrinsic 14715^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14716 14717Syntax: 14718""""""" 14719 14720:: 14721 14722 declare <type> 14723 @llvm.experimental.constrained.fdiv(<type> <op1>, <type> <op2>, 14724 metadata <rounding mode>, 14725 metadata <exception behavior>) 14726 14727Overview: 14728""""""""" 14729 14730The '``llvm.experimental.constrained.fdiv``' intrinsic returns the quotient of 14731its two operands. 14732 14733 14734Arguments: 14735"""""""""" 14736 14737The first two arguments to the '``llvm.experimental.constrained.fdiv``' 14738intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 14739of floating-point values. Both arguments must have identical types. 14740 14741The third and fourth arguments specify the rounding mode and exception 14742behavior as described above. 14743 14744Semantics: 14745"""""""""" 14746 14747The value produced is the floating-point quotient of the two value operands and 14748has the same type as the operands. 14749 14750 14751'``llvm.experimental.constrained.frem``' Intrinsic 14752^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14753 14754Syntax: 14755""""""" 14756 14757:: 14758 14759 declare <type> 14760 @llvm.experimental.constrained.frem(<type> <op1>, <type> <op2>, 14761 metadata <rounding mode>, 14762 metadata <exception behavior>) 14763 14764Overview: 14765""""""""" 14766 14767The '``llvm.experimental.constrained.frem``' intrinsic returns the remainder 14768from the division of its two operands. 14769 14770 14771Arguments: 14772"""""""""" 14773 14774The first two arguments to the '``llvm.experimental.constrained.frem``' 14775intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 14776of floating-point values. Both arguments must have identical types. 14777 14778The third and fourth arguments specify the rounding mode and exception 14779behavior as described above. The rounding mode argument has no effect, since 14780the result of frem is never rounded, but the argument is included for 14781consistency with the other constrained floating-point intrinsics. 14782 14783Semantics: 14784"""""""""" 14785 14786The value produced is the floating-point remainder from the division of the two 14787value operands and has the same type as the operands. The remainder has the 14788same sign as the dividend. 14789 14790'``llvm.experimental.constrained.fma``' Intrinsic 14791^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14792 14793Syntax: 14794""""""" 14795 14796:: 14797 14798 declare <type> 14799 @llvm.experimental.constrained.fma(<type> <op1>, <type> <op2>, <type> <op3>, 14800 metadata <rounding mode>, 14801 metadata <exception behavior>) 14802 14803Overview: 14804""""""""" 14805 14806The '``llvm.experimental.constrained.fma``' intrinsic returns the result of a 14807fused-multiply-add operation on its operands. 14808 14809Arguments: 14810"""""""""" 14811 14812The first three arguments to the '``llvm.experimental.constrained.fma``' 14813intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector 14814<t_vector>` of floating-point values. All arguments must have identical types. 14815 14816The fourth and fifth arguments specify the rounding mode and exception behavior 14817as described above. 14818 14819Semantics: 14820"""""""""" 14821 14822The result produced is the product of the first two operands added to the third 14823operand computed with infinite precision, and then rounded to the target 14824precision. 14825 14826Constrained libm-equivalent Intrinsics 14827-------------------------------------- 14828 14829In addition to the basic floating-point operations for which constrained 14830intrinsics are described above, there are constrained versions of various 14831operations which provide equivalent behavior to a corresponding libm function. 14832These intrinsics allow the precise behavior of these operations with respect to 14833rounding mode and exception behavior to be controlled. 14834 14835As with the basic constrained floating-point intrinsics, the rounding mode 14836and exception behavior arguments only control the behavior of the optimizer. 14837They do not change the runtime floating-point environment. 14838 14839 14840'``llvm.experimental.constrained.sqrt``' Intrinsic 14841^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14842 14843Syntax: 14844""""""" 14845 14846:: 14847 14848 declare <type> 14849 @llvm.experimental.constrained.sqrt(<type> <op1>, 14850 metadata <rounding mode>, 14851 metadata <exception behavior>) 14852 14853Overview: 14854""""""""" 14855 14856The '``llvm.experimental.constrained.sqrt``' intrinsic returns the square root 14857of the specified value, returning the same value as the libm '``sqrt``' 14858functions would, but without setting ``errno``. 14859 14860Arguments: 14861"""""""""" 14862 14863The first argument and the return type are floating-point numbers of the same 14864type. 14865 14866The second and third arguments specify the rounding mode and exception 14867behavior as described above. 14868 14869Semantics: 14870"""""""""" 14871 14872This function returns the nonnegative square root of the specified value. 14873If the value is less than negative zero, a floating-point exception occurs 14874and the return value is architecture specific. 14875 14876 14877'``llvm.experimental.constrained.pow``' Intrinsic 14878^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14879 14880Syntax: 14881""""""" 14882 14883:: 14884 14885 declare <type> 14886 @llvm.experimental.constrained.pow(<type> <op1>, <type> <op2>, 14887 metadata <rounding mode>, 14888 metadata <exception behavior>) 14889 14890Overview: 14891""""""""" 14892 14893The '``llvm.experimental.constrained.pow``' intrinsic returns the first operand 14894raised to the (positive or negative) power specified by the second operand. 14895 14896Arguments: 14897"""""""""" 14898 14899The first two arguments and the return value are floating-point numbers of the 14900same type. The second argument specifies the power to which the first argument 14901should be raised. 14902 14903The third and fourth arguments specify the rounding mode and exception 14904behavior as described above. 14905 14906Semantics: 14907"""""""""" 14908 14909This function returns the first value raised to the second power, 14910returning the same values as the libm ``pow`` functions would, and 14911handles error conditions in the same way. 14912 14913 14914'``llvm.experimental.constrained.powi``' Intrinsic 14915^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14916 14917Syntax: 14918""""""" 14919 14920:: 14921 14922 declare <type> 14923 @llvm.experimental.constrained.powi(<type> <op1>, i32 <op2>, 14924 metadata <rounding mode>, 14925 metadata <exception behavior>) 14926 14927Overview: 14928""""""""" 14929 14930The '``llvm.experimental.constrained.powi``' intrinsic returns the first operand 14931raised to the (positive or negative) power specified by the second operand. The 14932order of evaluation of multiplications is not defined. When a vector of 14933floating-point type is used, the second argument remains a scalar integer value. 14934 14935 14936Arguments: 14937"""""""""" 14938 14939The first argument and the return value are floating-point numbers of the same 14940type. The second argument is a 32-bit signed integer specifying the power to 14941which the first argument should be raised. 14942 14943The third and fourth arguments specify the rounding mode and exception 14944behavior as described above. 14945 14946Semantics: 14947"""""""""" 14948 14949This function returns the first value raised to the second power with an 14950unspecified sequence of rounding operations. 14951 14952 14953'``llvm.experimental.constrained.sin``' Intrinsic 14954^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14955 14956Syntax: 14957""""""" 14958 14959:: 14960 14961 declare <type> 14962 @llvm.experimental.constrained.sin(<type> <op1>, 14963 metadata <rounding mode>, 14964 metadata <exception behavior>) 14965 14966Overview: 14967""""""""" 14968 14969The '``llvm.experimental.constrained.sin``' intrinsic returns the sine of the 14970first operand. 14971 14972Arguments: 14973"""""""""" 14974 14975The first argument and the return type are floating-point numbers of the same 14976type. 14977 14978The second and third arguments specify the rounding mode and exception 14979behavior as described above. 14980 14981Semantics: 14982"""""""""" 14983 14984This function returns the sine of the specified operand, returning the 14985same values as the libm ``sin`` functions would, and handles error 14986conditions in the same way. 14987 14988 14989'``llvm.experimental.constrained.cos``' Intrinsic 14990^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14991 14992Syntax: 14993""""""" 14994 14995:: 14996 14997 declare <type> 14998 @llvm.experimental.constrained.cos(<type> <op1>, 14999 metadata <rounding mode>, 15000 metadata <exception behavior>) 15001 15002Overview: 15003""""""""" 15004 15005The '``llvm.experimental.constrained.cos``' intrinsic returns the cosine of the 15006first operand. 15007 15008Arguments: 15009"""""""""" 15010 15011The first argument and the return type are floating-point numbers of the same 15012type. 15013 15014The second and third arguments specify the rounding mode and exception 15015behavior as described above. 15016 15017Semantics: 15018"""""""""" 15019 15020This function returns the cosine of the specified operand, returning the 15021same values as the libm ``cos`` functions would, and handles error 15022conditions in the same way. 15023 15024 15025'``llvm.experimental.constrained.exp``' Intrinsic 15026^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15027 15028Syntax: 15029""""""" 15030 15031:: 15032 15033 declare <type> 15034 @llvm.experimental.constrained.exp(<type> <op1>, 15035 metadata <rounding mode>, 15036 metadata <exception behavior>) 15037 15038Overview: 15039""""""""" 15040 15041The '``llvm.experimental.constrained.exp``' intrinsic computes the base-e 15042exponential of the specified value. 15043 15044Arguments: 15045"""""""""" 15046 15047The first argument and the return value are floating-point numbers of the same 15048type. 15049 15050The second and third arguments specify the rounding mode and exception 15051behavior as described above. 15052 15053Semantics: 15054"""""""""" 15055 15056This function returns the same values as the libm ``exp`` functions 15057would, and handles error conditions in the same way. 15058 15059 15060'``llvm.experimental.constrained.exp2``' Intrinsic 15061^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15062 15063Syntax: 15064""""""" 15065 15066:: 15067 15068 declare <type> 15069 @llvm.experimental.constrained.exp2(<type> <op1>, 15070 metadata <rounding mode>, 15071 metadata <exception behavior>) 15072 15073Overview: 15074""""""""" 15075 15076The '``llvm.experimental.constrained.exp2``' intrinsic computes the base-2 15077exponential of the specified value. 15078 15079 15080Arguments: 15081"""""""""" 15082 15083The first argument and the return value are floating-point numbers of the same 15084type. 15085 15086The second and third arguments specify the rounding mode and exception 15087behavior as described above. 15088 15089Semantics: 15090"""""""""" 15091 15092This function returns the same values as the libm ``exp2`` functions 15093would, and handles error conditions in the same way. 15094 15095 15096'``llvm.experimental.constrained.log``' Intrinsic 15097^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15098 15099Syntax: 15100""""""" 15101 15102:: 15103 15104 declare <type> 15105 @llvm.experimental.constrained.log(<type> <op1>, 15106 metadata <rounding mode>, 15107 metadata <exception behavior>) 15108 15109Overview: 15110""""""""" 15111 15112The '``llvm.experimental.constrained.log``' intrinsic computes the base-e 15113logarithm of the specified value. 15114 15115Arguments: 15116"""""""""" 15117 15118The first argument and the return value are floating-point numbers of the same 15119type. 15120 15121The second and third arguments specify the rounding mode and exception 15122behavior as described above. 15123 15124 15125Semantics: 15126"""""""""" 15127 15128This function returns the same values as the libm ``log`` functions 15129would, and handles error conditions in the same way. 15130 15131 15132'``llvm.experimental.constrained.log10``' Intrinsic 15133^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15134 15135Syntax: 15136""""""" 15137 15138:: 15139 15140 declare <type> 15141 @llvm.experimental.constrained.log10(<type> <op1>, 15142 metadata <rounding mode>, 15143 metadata <exception behavior>) 15144 15145Overview: 15146""""""""" 15147 15148The '``llvm.experimental.constrained.log10``' intrinsic computes the base-10 15149logarithm of the specified value. 15150 15151Arguments: 15152"""""""""" 15153 15154The first argument and the return value are floating-point numbers of the same 15155type. 15156 15157The second and third arguments specify the rounding mode and exception 15158behavior as described above. 15159 15160Semantics: 15161"""""""""" 15162 15163This function returns the same values as the libm ``log10`` functions 15164would, and handles error conditions in the same way. 15165 15166 15167'``llvm.experimental.constrained.log2``' Intrinsic 15168^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15169 15170Syntax: 15171""""""" 15172 15173:: 15174 15175 declare <type> 15176 @llvm.experimental.constrained.log2(<type> <op1>, 15177 metadata <rounding mode>, 15178 metadata <exception behavior>) 15179 15180Overview: 15181""""""""" 15182 15183The '``llvm.experimental.constrained.log2``' intrinsic computes the base-2 15184logarithm of the specified value. 15185 15186Arguments: 15187"""""""""" 15188 15189The first argument and the return value are floating-point numbers of the same 15190type. 15191 15192The second and third arguments specify the rounding mode and exception 15193behavior as described above. 15194 15195Semantics: 15196"""""""""" 15197 15198This function returns the same values as the libm ``log2`` functions 15199would, and handles error conditions in the same way. 15200 15201 15202'``llvm.experimental.constrained.rint``' Intrinsic 15203^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15204 15205Syntax: 15206""""""" 15207 15208:: 15209 15210 declare <type> 15211 @llvm.experimental.constrained.rint(<type> <op1>, 15212 metadata <rounding mode>, 15213 metadata <exception behavior>) 15214 15215Overview: 15216""""""""" 15217 15218The '``llvm.experimental.constrained.rint``' intrinsic returns the first 15219operand rounded to the nearest integer. It may raise an inexact floating-point 15220exception if the operand is not an integer. 15221 15222Arguments: 15223"""""""""" 15224 15225The first argument and the return value are floating-point numbers of the same 15226type. 15227 15228The second and third arguments specify the rounding mode and exception 15229behavior as described above. 15230 15231Semantics: 15232"""""""""" 15233 15234This function returns the same values as the libm ``rint`` functions 15235would, and handles error conditions in the same way. The rounding mode is 15236described, not determined, by the rounding mode argument. The actual rounding 15237mode is determined by the runtime floating-point environment. The rounding 15238mode argument is only intended as information to the compiler. 15239 15240 15241'``llvm.experimental.constrained.nearbyint``' Intrinsic 15242^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15243 15244Syntax: 15245""""""" 15246 15247:: 15248 15249 declare <type> 15250 @llvm.experimental.constrained.nearbyint(<type> <op1>, 15251 metadata <rounding mode>, 15252 metadata <exception behavior>) 15253 15254Overview: 15255""""""""" 15256 15257The '``llvm.experimental.constrained.nearbyint``' intrinsic returns the first 15258operand rounded to the nearest integer. It will not raise an inexact 15259floating-point exception if the operand is not an integer. 15260 15261 15262Arguments: 15263"""""""""" 15264 15265The first argument and the return value are floating-point numbers of the same 15266type. 15267 15268The second and third arguments specify the rounding mode and exception 15269behavior as described above. 15270 15271Semantics: 15272"""""""""" 15273 15274This function returns the same values as the libm ``nearbyint`` functions 15275would, and handles error conditions in the same way. The rounding mode is 15276described, not determined, by the rounding mode argument. The actual rounding 15277mode is determined by the runtime floating-point environment. The rounding 15278mode argument is only intended as information to the compiler. 15279 15280 15281'``llvm.experimental.constrained.maxnum``' Intrinsic 15282^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15283 15284Syntax: 15285""""""" 15286 15287:: 15288 15289 declare <type> 15290 @llvm.experimental.constrained.maxnum(<type> <op1>, <type> <op2> 15291 metadata <rounding mode>, 15292 metadata <exception behavior>) 15293 15294Overview: 15295""""""""" 15296 15297The '``llvm.experimental.constrained.maxnum``' intrinsic returns the maximum 15298of the two arguments. 15299 15300Arguments: 15301"""""""""" 15302 15303The first two arguments and the return value are floating-point numbers 15304of the same type. 15305 15306The third and forth arguments specify the rounding mode and exception 15307behavior as described above. 15308 15309Semantics: 15310"""""""""" 15311 15312This function follows the IEEE-754 semantics for maxNum. The rounding mode is 15313described, not determined, by the rounding mode argument. The actual rounding 15314mode is determined by the runtime floating-point environment. The rounding 15315mode argument is only intended as information to the compiler. 15316 15317 15318'``llvm.experimental.constrained.minnum``' Intrinsic 15319^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15320 15321Syntax: 15322""""""" 15323 15324:: 15325 15326 declare <type> 15327 @llvm.experimental.constrained.minnum(<type> <op1>, <type> <op2> 15328 metadata <rounding mode>, 15329 metadata <exception behavior>) 15330 15331Overview: 15332""""""""" 15333 15334The '``llvm.experimental.constrained.minnum``' intrinsic returns the minimum 15335of the two arguments. 15336 15337Arguments: 15338"""""""""" 15339 15340The first two arguments and the return value are floating-point numbers 15341of the same type. 15342 15343The third and forth arguments specify the rounding mode and exception 15344behavior as described above. 15345 15346Semantics: 15347"""""""""" 15348 15349This function follows the IEEE-754 semantics for minNum. The rounding mode is 15350described, not determined, by the rounding mode argument. The actual rounding 15351mode is determined by the runtime floating-point environment. The rounding 15352mode argument is only intended as information to the compiler. 15353 15354 15355'``llvm.experimental.constrained.ceil``' Intrinsic 15356^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15357 15358Syntax: 15359""""""" 15360 15361:: 15362 15363 declare <type> 15364 @llvm.experimental.constrained.ceil(<type> <op1>, 15365 metadata <rounding mode>, 15366 metadata <exception behavior>) 15367 15368Overview: 15369""""""""" 15370 15371The '``llvm.experimental.constrained.ceil``' intrinsic returns the ceiling of the 15372first operand. 15373 15374Arguments: 15375"""""""""" 15376 15377The first argument and the return value are floating-point numbers of the same 15378type. 15379 15380The second and third arguments specify the rounding mode and exception 15381behavior as described above. The rounding mode is currently unused for this 15382intrinsic. 15383 15384Semantics: 15385"""""""""" 15386 15387This function returns the same values as the libm ``ceil`` functions 15388would and handles error conditions in the same way. 15389 15390 15391'``llvm.experimental.constrained.floor``' Intrinsic 15392^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15393 15394Syntax: 15395""""""" 15396 15397:: 15398 15399 declare <type> 15400 @llvm.experimental.constrained.floor(<type> <op1>, 15401 metadata <rounding mode>, 15402 metadata <exception behavior>) 15403 15404Overview: 15405""""""""" 15406 15407The '``llvm.experimental.constrained.floor``' intrinsic returns the floor of the 15408first operand. 15409 15410Arguments: 15411"""""""""" 15412 15413The first argument and the return value are floating-point numbers of the same 15414type. 15415 15416The second and third arguments specify the rounding mode and exception 15417behavior as described above. The rounding mode is currently unused for this 15418intrinsic. 15419 15420Semantics: 15421"""""""""" 15422 15423This function returns the same values as the libm ``floor`` functions 15424would and handles error conditions in the same way. 15425 15426 15427'``llvm.experimental.constrained.round``' Intrinsic 15428^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15429 15430Syntax: 15431""""""" 15432 15433:: 15434 15435 declare <type> 15436 @llvm.experimental.constrained.round(<type> <op1>, 15437 metadata <rounding mode>, 15438 metadata <exception behavior>) 15439 15440Overview: 15441""""""""" 15442 15443The '``llvm.experimental.constrained.round``' intrinsic returns the first 15444operand rounded to the nearest integer. 15445 15446Arguments: 15447"""""""""" 15448 15449The first argument and the return value are floating-point numbers of the same 15450type. 15451 15452The second and third arguments specify the rounding mode and exception 15453behavior as described above. The rounding mode is currently unused for this 15454intrinsic. 15455 15456Semantics: 15457"""""""""" 15458 15459This function returns the same values as the libm ``round`` functions 15460would and handles error conditions in the same way. 15461 15462 15463'``llvm.experimental.constrained.trunc``' Intrinsic 15464^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15465 15466Syntax: 15467""""""" 15468 15469:: 15470 15471 declare <type> 15472 @llvm.experimental.constrained.trunc(<type> <op1>, 15473 metadata <truncing mode>, 15474 metadata <exception behavior>) 15475 15476Overview: 15477""""""""" 15478 15479The '``llvm.experimental.constrained.trunc``' intrinsic returns the first 15480operand rounded to the nearest integer not larger in magnitude than the 15481operand. 15482 15483Arguments: 15484"""""""""" 15485 15486The first argument and the return value are floating-point numbers of the same 15487type. 15488 15489The second and third arguments specify the truncing mode and exception 15490behavior as described above. The truncing mode is currently unused for this 15491intrinsic. 15492 15493Semantics: 15494"""""""""" 15495 15496This function returns the same values as the libm ``trunc`` functions 15497would and handles error conditions in the same way. 15498 15499 15500General Intrinsics 15501------------------ 15502 15503This class of intrinsics is designed to be generic and has no specific 15504purpose. 15505 15506'``llvm.var.annotation``' Intrinsic 15507^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15508 15509Syntax: 15510""""""" 15511 15512:: 15513 15514 declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>) 15515 15516Overview: 15517""""""""" 15518 15519The '``llvm.var.annotation``' intrinsic. 15520 15521Arguments: 15522"""""""""" 15523 15524The first argument is a pointer to a value, the second is a pointer to a 15525global string, the third is a pointer to a global string which is the 15526source file name, and the last argument is the line number. 15527 15528Semantics: 15529"""""""""" 15530 15531This intrinsic allows annotation of local variables with arbitrary 15532strings. This can be useful for special purpose optimizations that want 15533to look for these annotations. These have no other defined use; they are 15534ignored by code generation and optimization. 15535 15536'``llvm.ptr.annotation.*``' Intrinsic 15537^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15538 15539Syntax: 15540""""""" 15541 15542This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a 15543pointer to an integer of any width. *NOTE* you must specify an address space for 15544the pointer. The identifier for the default address space is the integer 15545'``0``'. 15546 15547:: 15548 15549 declare i8* @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32 <int>) 15550 declare i16* @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32 <int>) 15551 declare i32* @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32 <int>) 15552 declare i64* @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32 <int>) 15553 declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32 <int>) 15554 15555Overview: 15556""""""""" 15557 15558The '``llvm.ptr.annotation``' intrinsic. 15559 15560Arguments: 15561"""""""""" 15562 15563The first argument is a pointer to an integer value of arbitrary bitwidth 15564(result of some expression), the second is a pointer to a global string, the 15565third is a pointer to a global string which is the source file name, and the 15566last argument is the line number. It returns the value of the first argument. 15567 15568Semantics: 15569"""""""""" 15570 15571This intrinsic allows annotation of a pointer to an integer with arbitrary 15572strings. This can be useful for special purpose optimizations that want to look 15573for these annotations. These have no other defined use; they are ignored by code 15574generation and optimization. 15575 15576'``llvm.annotation.*``' Intrinsic 15577^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15578 15579Syntax: 15580""""""" 15581 15582This is an overloaded intrinsic. You can use '``llvm.annotation``' on 15583any integer bit width. 15584 15585:: 15586 15587 declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>) 15588 declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>) 15589 declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>) 15590 declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>) 15591 declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>) 15592 15593Overview: 15594""""""""" 15595 15596The '``llvm.annotation``' intrinsic. 15597 15598Arguments: 15599"""""""""" 15600 15601The first argument is an integer value (result of some expression), the 15602second is a pointer to a global string, the third is a pointer to a 15603global string which is the source file name, and the last argument is 15604the line number. It returns the value of the first argument. 15605 15606Semantics: 15607"""""""""" 15608 15609This intrinsic allows annotations to be put on arbitrary expressions 15610with arbitrary strings. This can be useful for special purpose 15611optimizations that want to look for these annotations. These have no 15612other defined use; they are ignored by code generation and optimization. 15613 15614'``llvm.codeview.annotation``' Intrinsic 15615^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15616 15617Syntax: 15618""""""" 15619 15620This annotation emits a label at its program point and an associated 15621``S_ANNOTATION`` codeview record with some additional string metadata. This is 15622used to implement MSVC's ``__annotation`` intrinsic. It is marked 15623``noduplicate``, so calls to this intrinsic prevent inlining and should be 15624considered expensive. 15625 15626:: 15627 15628 declare void @llvm.codeview.annotation(metadata) 15629 15630Arguments: 15631"""""""""" 15632 15633The argument should be an MDTuple containing any number of MDStrings. 15634 15635'``llvm.trap``' Intrinsic 15636^^^^^^^^^^^^^^^^^^^^^^^^^ 15637 15638Syntax: 15639""""""" 15640 15641:: 15642 15643 declare void @llvm.trap() cold noreturn nounwind 15644 15645Overview: 15646""""""""" 15647 15648The '``llvm.trap``' intrinsic. 15649 15650Arguments: 15651"""""""""" 15652 15653None. 15654 15655Semantics: 15656"""""""""" 15657 15658This intrinsic is lowered to the target dependent trap instruction. If 15659the target does not have a trap instruction, this intrinsic will be 15660lowered to a call of the ``abort()`` function. 15661 15662'``llvm.debugtrap``' Intrinsic 15663^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15664 15665Syntax: 15666""""""" 15667 15668:: 15669 15670 declare void @llvm.debugtrap() nounwind 15671 15672Overview: 15673""""""""" 15674 15675The '``llvm.debugtrap``' intrinsic. 15676 15677Arguments: 15678"""""""""" 15679 15680None. 15681 15682Semantics: 15683"""""""""" 15684 15685This intrinsic is lowered to code which is intended to cause an 15686execution trap with the intention of requesting the attention of a 15687debugger. 15688 15689'``llvm.stackprotector``' Intrinsic 15690^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15691 15692Syntax: 15693""""""" 15694 15695:: 15696 15697 declare void @llvm.stackprotector(i8* <guard>, i8** <slot>) 15698 15699Overview: 15700""""""""" 15701 15702The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it 15703onto the stack at ``slot``. The stack slot is adjusted to ensure that it 15704is placed on the stack before local variables. 15705 15706Arguments: 15707"""""""""" 15708 15709The ``llvm.stackprotector`` intrinsic requires two pointer arguments. 15710The first argument is the value loaded from the stack guard 15711``@__stack_chk_guard``. The second variable is an ``alloca`` that has 15712enough space to hold the value of the guard. 15713 15714Semantics: 15715"""""""""" 15716 15717This intrinsic causes the prologue/epilogue inserter to force the position of 15718the ``AllocaInst`` stack slot to be before local variables on the stack. This is 15719to ensure that if a local variable on the stack is overwritten, it will destroy 15720the value of the guard. When the function exits, the guard on the stack is 15721checked against the original guard by ``llvm.stackprotectorcheck``. If they are 15722different, then ``llvm.stackprotectorcheck`` causes the program to abort by 15723calling the ``__stack_chk_fail()`` function. 15724 15725'``llvm.stackguard``' Intrinsic 15726^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15727 15728Syntax: 15729""""""" 15730 15731:: 15732 15733 declare i8* @llvm.stackguard() 15734 15735Overview: 15736""""""""" 15737 15738The ``llvm.stackguard`` intrinsic returns the system stack guard value. 15739 15740It should not be generated by frontends, since it is only for internal usage. 15741The reason why we create this intrinsic is that we still support IR form Stack 15742Protector in FastISel. 15743 15744Arguments: 15745"""""""""" 15746 15747None. 15748 15749Semantics: 15750"""""""""" 15751 15752On some platforms, the value returned by this intrinsic remains unchanged 15753between loads in the same thread. On other platforms, it returns the same 15754global variable value, if any, e.g. ``@__stack_chk_guard``. 15755 15756Currently some platforms have IR-level customized stack guard loading (e.g. 15757X86 Linux) that is not handled by ``llvm.stackguard()``, while they should be 15758in the future. 15759 15760'``llvm.objectsize``' Intrinsic 15761^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15762 15763Syntax: 15764""""""" 15765 15766:: 15767 15768 declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>) 15769 declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>) 15770 15771Overview: 15772""""""""" 15773 15774The ``llvm.objectsize`` intrinsic is designed to provide information to the 15775optimizer to determine whether a) an operation (like memcpy) will overflow a 15776buffer that corresponds to an object, or b) that a runtime check for overflow 15777isn't necessary. An object in this context means an allocation of a specific 15778class, structure, array, or other object. 15779 15780Arguments: 15781"""""""""" 15782 15783The ``llvm.objectsize`` intrinsic takes four arguments. The first argument is a 15784pointer to or into the ``object``. The second argument determines whether 15785``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size is 15786unknown. The third argument controls how ``llvm.objectsize`` acts when ``null`` 15787in address space 0 is used as its pointer argument. If it's ``false``, 15788``llvm.objectsize`` reports 0 bytes available when given ``null``. Otherwise, if 15789the ``null`` is in a non-zero address space or if ``true`` is given for the 15790third argument of ``llvm.objectsize``, we assume its size is unknown. The fourth 15791argument to ``llvm.objectsize`` determines if the value should be evaluated at 15792runtime. 15793 15794The second, third, and fourth arguments only accept constants. 15795 15796Semantics: 15797"""""""""" 15798 15799The ``llvm.objectsize`` intrinsic is lowered to a value representing the size of 15800the object concerned. If the size cannot be determined, ``llvm.objectsize`` 15801returns ``i32/i64 -1 or 0`` (depending on the ``min`` argument). 15802 15803'``llvm.expect``' Intrinsic 15804^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15805 15806Syntax: 15807""""""" 15808 15809This is an overloaded intrinsic. You can use ``llvm.expect`` on any 15810integer bit width. 15811 15812:: 15813 15814 declare i1 @llvm.expect.i1(i1 <val>, i1 <expected_val>) 15815 declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>) 15816 declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>) 15817 15818Overview: 15819""""""""" 15820 15821The ``llvm.expect`` intrinsic provides information about expected (the 15822most probable) value of ``val``, which can be used by optimizers. 15823 15824Arguments: 15825"""""""""" 15826 15827The ``llvm.expect`` intrinsic takes two arguments. The first argument is 15828a value. The second argument is an expected value. 15829 15830Semantics: 15831"""""""""" 15832 15833This intrinsic is lowered to the ``val``. 15834 15835.. _int_assume: 15836 15837'``llvm.assume``' Intrinsic 15838^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15839 15840Syntax: 15841""""""" 15842 15843:: 15844 15845 declare void @llvm.assume(i1 %cond) 15846 15847Overview: 15848""""""""" 15849 15850The ``llvm.assume`` allows the optimizer to assume that the provided 15851condition is true. This information can then be used in simplifying other parts 15852of the code. 15853 15854Arguments: 15855"""""""""" 15856 15857The condition which the optimizer may assume is always true. 15858 15859Semantics: 15860"""""""""" 15861 15862The intrinsic allows the optimizer to assume that the provided condition is 15863always true whenever the control flow reaches the intrinsic call. No code is 15864generated for this intrinsic, and instructions that contribute only to the 15865provided condition are not used for code generation. If the condition is 15866violated during execution, the behavior is undefined. 15867 15868Note that the optimizer might limit the transformations performed on values 15869used by the ``llvm.assume`` intrinsic in order to preserve the instructions 15870only used to form the intrinsic's input argument. This might prove undesirable 15871if the extra information provided by the ``llvm.assume`` intrinsic does not cause 15872sufficient overall improvement in code quality. For this reason, 15873``llvm.assume`` should not be used to document basic mathematical invariants 15874that the optimizer can otherwise deduce or facts that are of little use to the 15875optimizer. 15876 15877.. _int_ssa_copy: 15878 15879'``llvm.ssa_copy``' Intrinsic 15880^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15881 15882Syntax: 15883""""""" 15884 15885:: 15886 15887 declare type @llvm.ssa_copy(type %operand) returned(1) readnone 15888 15889Arguments: 15890"""""""""" 15891 15892The first argument is an operand which is used as the returned value. 15893 15894Overview: 15895"""""""""" 15896 15897The ``llvm.ssa_copy`` intrinsic can be used to attach information to 15898operations by copying them and giving them new names. For example, 15899the PredicateInfo utility uses it to build Extended SSA form, and 15900attach various forms of information to operands that dominate specific 15901uses. It is not meant for general use, only for building temporary 15902renaming forms that require value splits at certain points. 15903 15904.. _type.test: 15905 15906'``llvm.type.test``' Intrinsic 15907^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15908 15909Syntax: 15910""""""" 15911 15912:: 15913 15914 declare i1 @llvm.type.test(i8* %ptr, metadata %type) nounwind readnone 15915 15916 15917Arguments: 15918"""""""""" 15919 15920The first argument is a pointer to be tested. The second argument is a 15921metadata object representing a :doc:`type identifier <TypeMetadata>`. 15922 15923Overview: 15924""""""""" 15925 15926The ``llvm.type.test`` intrinsic tests whether the given pointer is associated 15927with the given type identifier. 15928 15929'``llvm.type.checked.load``' Intrinsic 15930^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15931 15932Syntax: 15933""""""" 15934 15935:: 15936 15937 declare {i8*, i1} @llvm.type.checked.load(i8* %ptr, i32 %offset, metadata %type) argmemonly nounwind readonly 15938 15939 15940Arguments: 15941"""""""""" 15942 15943The first argument is a pointer from which to load a function pointer. The 15944second argument is the byte offset from which to load the function pointer. The 15945third argument is a metadata object representing a :doc:`type identifier 15946<TypeMetadata>`. 15947 15948Overview: 15949""""""""" 15950 15951The ``llvm.type.checked.load`` intrinsic safely loads a function pointer from a 15952virtual table pointer using type metadata. This intrinsic is used to implement 15953control flow integrity in conjunction with virtual call optimization. The 15954virtual call optimization pass will optimize away ``llvm.type.checked.load`` 15955intrinsics associated with devirtualized calls, thereby removing the type 15956check in cases where it is not needed to enforce the control flow integrity 15957constraint. 15958 15959If the given pointer is associated with a type metadata identifier, this 15960function returns true as the second element of its return value. (Note that 15961the function may also return true if the given pointer is not associated 15962with a type metadata identifier.) If the function's return value's second 15963element is true, the following rules apply to the first element: 15964 15965- If the given pointer is associated with the given type metadata identifier, 15966 it is the function pointer loaded from the given byte offset from the given 15967 pointer. 15968 15969- If the given pointer is not associated with the given type metadata 15970 identifier, it is one of the following (the choice of which is unspecified): 15971 15972 1. The function pointer that would have been loaded from an arbitrarily chosen 15973 (through an unspecified mechanism) pointer associated with the type 15974 metadata. 15975 15976 2. If the function has a non-void return type, a pointer to a function that 15977 returns an unspecified value without causing side effects. 15978 15979If the function's return value's second element is false, the value of the 15980first element is undefined. 15981 15982 15983'``llvm.donothing``' Intrinsic 15984^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15985 15986Syntax: 15987""""""" 15988 15989:: 15990 15991 declare void @llvm.donothing() nounwind readnone 15992 15993Overview: 15994""""""""" 15995 15996The ``llvm.donothing`` intrinsic doesn't perform any operation. It's one of only 15997three intrinsics (besides ``llvm.experimental.patchpoint`` and 15998``llvm.experimental.gc.statepoint``) that can be called with an invoke 15999instruction. 16000 16001Arguments: 16002"""""""""" 16003 16004None. 16005 16006Semantics: 16007"""""""""" 16008 16009This intrinsic does nothing, and it's removed by optimizers and ignored 16010by codegen. 16011 16012'``llvm.experimental.deoptimize``' Intrinsic 16013^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16014 16015Syntax: 16016""""""" 16017 16018:: 16019 16020 declare type @llvm.experimental.deoptimize(...) [ "deopt"(...) ] 16021 16022Overview: 16023""""""""" 16024 16025This intrinsic, together with :ref:`deoptimization operand bundles 16026<deopt_opbundles>`, allow frontends to express transfer of control and 16027frame-local state from the currently executing (typically more specialized, 16028hence faster) version of a function into another (typically more generic, hence 16029slower) version. 16030 16031In languages with a fully integrated managed runtime like Java and JavaScript 16032this intrinsic can be used to implement "uncommon trap" or "side exit" like 16033functionality. In unmanaged languages like C and C++, this intrinsic can be 16034used to represent the slow paths of specialized functions. 16035 16036 16037Arguments: 16038"""""""""" 16039 16040The intrinsic takes an arbitrary number of arguments, whose meaning is 16041decided by the :ref:`lowering strategy<deoptimize_lowering>`. 16042 16043Semantics: 16044"""""""""" 16045 16046The ``@llvm.experimental.deoptimize`` intrinsic executes an attached 16047deoptimization continuation (denoted using a :ref:`deoptimization 16048operand bundle <deopt_opbundles>`) and returns the value returned by 16049the deoptimization continuation. Defining the semantic properties of 16050the continuation itself is out of scope of the language reference -- 16051as far as LLVM is concerned, the deoptimization continuation can 16052invoke arbitrary side effects, including reading from and writing to 16053the entire heap. 16054 16055Deoptimization continuations expressed using ``"deopt"`` operand bundles always 16056continue execution to the end of the physical frame containing them, so all 16057calls to ``@llvm.experimental.deoptimize`` must be in "tail position": 16058 16059 - ``@llvm.experimental.deoptimize`` cannot be invoked. 16060 - The call must immediately precede a :ref:`ret <i_ret>` instruction. 16061 - The ``ret`` instruction must return the value produced by the 16062 ``@llvm.experimental.deoptimize`` call if there is one, or void. 16063 16064Note that the above restrictions imply that the return type for a call to 16065``@llvm.experimental.deoptimize`` will match the return type of its immediate 16066caller. 16067 16068The inliner composes the ``"deopt"`` continuations of the caller into the 16069``"deopt"`` continuations present in the inlinee, and also updates calls to this 16070intrinsic to return directly from the frame of the function it inlined into. 16071 16072All declarations of ``@llvm.experimental.deoptimize`` must share the 16073same calling convention. 16074 16075.. _deoptimize_lowering: 16076 16077Lowering: 16078""""""""" 16079 16080Calls to ``@llvm.experimental.deoptimize`` are lowered to calls to the 16081symbol ``__llvm_deoptimize`` (it is the frontend's responsibility to 16082ensure that this symbol is defined). The call arguments to 16083``@llvm.experimental.deoptimize`` are lowered as if they were formal 16084arguments of the specified types, and not as varargs. 16085 16086 16087'``llvm.experimental.guard``' Intrinsic 16088^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16089 16090Syntax: 16091""""""" 16092 16093:: 16094 16095 declare void @llvm.experimental.guard(i1, ...) [ "deopt"(...) ] 16096 16097Overview: 16098""""""""" 16099 16100This intrinsic, together with :ref:`deoptimization operand bundles 16101<deopt_opbundles>`, allows frontends to express guards or checks on 16102optimistic assumptions made during compilation. The semantics of 16103``@llvm.experimental.guard`` is defined in terms of 16104``@llvm.experimental.deoptimize`` -- its body is defined to be 16105equivalent to: 16106 16107.. code-block:: text 16108 16109 define void @llvm.experimental.guard(i1 %pred, <args...>) { 16110 %realPred = and i1 %pred, undef 16111 br i1 %realPred, label %continue, label %leave [, !make.implicit !{}] 16112 16113 leave: 16114 call void @llvm.experimental.deoptimize(<args...>) [ "deopt"() ] 16115 ret void 16116 16117 continue: 16118 ret void 16119 } 16120 16121 16122with the optional ``[, !make.implicit !{}]`` present if and only if it 16123is present on the call site. For more details on ``!make.implicit``, 16124see :doc:`FaultMaps`. 16125 16126In words, ``@llvm.experimental.guard`` executes the attached 16127``"deopt"`` continuation if (but **not** only if) its first argument 16128is ``false``. Since the optimizer is allowed to replace the ``undef`` 16129with an arbitrary value, it can optimize guard to fail "spuriously", 16130i.e. without the original condition being false (hence the "not only 16131if"); and this allows for "check widening" type optimizations. 16132 16133``@llvm.experimental.guard`` cannot be invoked. 16134 16135 16136'``llvm.experimental.widenable.condition``' Intrinsic 16137^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16138 16139Syntax: 16140""""""" 16141 16142:: 16143 16144 declare i1 @llvm.experimental.widenable.condition() 16145 16146Overview: 16147""""""""" 16148 16149This intrinsic represents a "widenable condition" which is 16150boolean expressions with the following property: whether this 16151expression is `true` or `false`, the program is correct and 16152well-defined. 16153 16154Together with :ref:`deoptimization operand bundles <deopt_opbundles>`, 16155``@llvm.experimental.widenable.condition`` allows frontends to 16156express guards or checks on optimistic assumptions made during 16157compilation and represent them as branch instructions on special 16158conditions. 16159 16160While this may appear similar in semantics to `undef`, it is very 16161different in that an invocation produces a particular, singular 16162value. It is also intended to be lowered late, and remain available 16163for specific optimizations and transforms that can benefit from its 16164special properties. 16165 16166Arguments: 16167"""""""""" 16168 16169None. 16170 16171Semantics: 16172"""""""""" 16173 16174The intrinsic ``@llvm.experimental.widenable.condition()`` 16175returns either `true` or `false`. For each evaluation of a call 16176to this intrinsic, the program must be valid and correct both if 16177it returns `true` and if it returns `false`. This allows 16178transformation passes to replace evaluations of this intrinsic 16179with either value whenever one is beneficial. 16180 16181When used in a branch condition, it allows us to choose between 16182two alternative correct solutions for the same problem, like 16183in example below: 16184 16185.. code-block:: text 16186 16187 %cond = call i1 @llvm.experimental.widenable.condition() 16188 br i1 %cond, label %solution_1, label %solution_2 16189 16190 label %fast_path: 16191 ; Apply memory-consuming but fast solution for a task. 16192 16193 label %slow_path: 16194 ; Cheap in memory but slow solution. 16195 16196Whether the result of intrinsic's call is `true` or `false`, 16197it should be correct to pick either solution. We can switch 16198between them by replacing the result of 16199``@llvm.experimental.widenable.condition`` with different 16200`i1` expressions. 16201 16202This is how it can be used to represent guards as widenable branches: 16203 16204.. code-block:: text 16205 16206 block: 16207 ; Unguarded instructions 16208 call void @llvm.experimental.guard(i1 %cond, <args...>) ["deopt"(<deopt_args...>)] 16209 ; Guarded instructions 16210 16211Can be expressed in an alternative equivalent form of explicit branch using 16212``@llvm.experimental.widenable.condition``: 16213 16214.. code-block:: text 16215 16216 block: 16217 ; Unguarded instructions 16218 %widenable_condition = call i1 @llvm.experimental.widenable.condition() 16219 %guard_condition = and i1 %cond, %widenable_condition 16220 br i1 %guard_condition, label %guarded, label %deopt 16221 16222 guarded: 16223 ; Guarded instructions 16224 16225 deopt: 16226 call type @llvm.experimental.deoptimize(<args...>) [ "deopt"(<deopt_args...>) ] 16227 16228So the block `guarded` is only reachable when `%cond` is `true`, 16229and it should be valid to go to the block `deopt` whenever `%cond` 16230is `true` or `false`. 16231 16232``@llvm.experimental.widenable.condition`` will never throw, thus 16233it cannot be invoked. 16234 16235Guard widening: 16236""""""""""""""" 16237 16238When ``@llvm.experimental.widenable.condition()`` is used in 16239condition of a guard represented as explicit branch, it is 16240legal to widen the guard's condition with any additional 16241conditions. 16242 16243Guard widening looks like replacement of 16244 16245.. code-block:: text 16246 16247 %widenable_cond = call i1 @llvm.experimental.widenable.condition() 16248 %guard_cond = and i1 %cond, %widenable_cond 16249 br i1 %guard_cond, label %guarded, label %deopt 16250 16251with 16252 16253.. code-block:: text 16254 16255 %widenable_cond = call i1 @llvm.experimental.widenable.condition() 16256 %new_cond = and i1 %any_other_cond, %widenable_cond 16257 %new_guard_cond = and i1 %cond, %new_cond 16258 br i1 %new_guard_cond, label %guarded, label %deopt 16259 16260for this branch. Here `%any_other_cond` is an arbitrarily chosen 16261well-defined `i1` value. By making guard widening, we may 16262impose stricter conditions on `guarded` block and bail to the 16263deopt when the new condition is not met. 16264 16265Lowering: 16266""""""""" 16267 16268Default lowering strategy is replacing the result of 16269call of ``@llvm.experimental.widenable.condition`` with 16270constant `true`. However it is always correct to replace 16271it with any other `i1` value. Any pass can 16272freely do it if it can benefit from non-default lowering. 16273 16274 16275'``llvm.load.relative``' Intrinsic 16276^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16277 16278Syntax: 16279""""""" 16280 16281:: 16282 16283 declare i8* @llvm.load.relative.iN(i8* %ptr, iN %offset) argmemonly nounwind readonly 16284 16285Overview: 16286""""""""" 16287 16288This intrinsic loads a 32-bit value from the address ``%ptr + %offset``, 16289adds ``%ptr`` to that value and returns it. The constant folder specifically 16290recognizes the form of this intrinsic and the constant initializers it may 16291load from; if a loaded constant initializer is known to have the form 16292``i32 trunc(x - %ptr)``, the intrinsic call is folded to ``x``. 16293 16294LLVM provides that the calculation of such a constant initializer will 16295not overflow at link time under the medium code model if ``x`` is an 16296``unnamed_addr`` function. However, it does not provide this guarantee for 16297a constant initializer folded into a function body. This intrinsic can be 16298used to avoid the possibility of overflows when loading from such a constant. 16299 16300'``llvm.sideeffect``' Intrinsic 16301^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16302 16303Syntax: 16304""""""" 16305 16306:: 16307 16308 declare void @llvm.sideeffect() inaccessiblememonly nounwind 16309 16310Overview: 16311""""""""" 16312 16313The ``llvm.sideeffect`` intrinsic doesn't perform any operation. Optimizers 16314treat it as having side effects, so it can be inserted into a loop to 16315indicate that the loop shouldn't be assumed to terminate (which could 16316potentially lead to the loop being optimized away entirely), even if it's 16317an infinite loop with no other side effects. 16318 16319Arguments: 16320"""""""""" 16321 16322None. 16323 16324Semantics: 16325"""""""""" 16326 16327This intrinsic actually does nothing, but optimizers must assume that it 16328has externally observable side effects. 16329 16330'``llvm.is.constant.*``' Intrinsic 16331^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16332 16333Syntax: 16334""""""" 16335 16336This is an overloaded intrinsic. You can use llvm.is.constant with any argument type. 16337 16338:: 16339 16340 declare i1 @llvm.is.constant.i32(i32 %operand) nounwind readnone 16341 declare i1 @llvm.is.constant.f32(float %operand) nounwind readnone 16342 declare i1 @llvm.is.constant.TYPENAME(TYPE %operand) nounwind readnone 16343 16344Overview: 16345""""""""" 16346 16347The '``llvm.is.constant``' intrinsic will return true if the argument 16348is known to be a manifest compile-time constant. It is guaranteed to 16349fold to either true or false before generating machine code. 16350 16351Semantics: 16352"""""""""" 16353 16354This intrinsic generates no code. If its argument is known to be a 16355manifest compile-time constant value, then the intrinsic will be 16356converted to a constant true value. Otherwise, it will be converted to 16357a constant false value. 16358 16359In particular, note that if the argument is a constant expression 16360which refers to a global (the address of which _is_ a constant, but 16361not manifest during the compile), then the intrinsic evaluates to 16362false. 16363 16364The result also intentionally depends on the result of optimization 16365passes -- e.g., the result can change depending on whether a 16366function gets inlined or not. A function's parameters are 16367obviously not constant. However, a call like 16368``llvm.is.constant.i32(i32 %param)`` *can* return true after the 16369function is inlined, if the value passed to the function parameter was 16370a constant. 16371 16372On the other hand, if constant folding is not run, it will never 16373evaluate to true, even in simple cases. 16374 16375Stack Map Intrinsics 16376-------------------- 16377 16378LLVM provides experimental intrinsics to support runtime patching 16379mechanisms commonly desired in dynamic language JITs. These intrinsics 16380are described in :doc:`StackMaps`. 16381 16382Element Wise Atomic Memory Intrinsics 16383------------------------------------- 16384 16385These intrinsics are similar to the standard library memory intrinsics except 16386that they perform memory transfer as a sequence of atomic memory accesses. 16387 16388.. _int_memcpy_element_unordered_atomic: 16389 16390'``llvm.memcpy.element.unordered.atomic``' Intrinsic 16391^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16392 16393Syntax: 16394""""""" 16395 16396This is an overloaded intrinsic. You can use ``llvm.memcpy.element.unordered.atomic`` on 16397any integer bit width and for different address spaces. Not all targets 16398support all bit widths however. 16399 16400:: 16401 16402 declare void @llvm.memcpy.element.unordered.atomic.p0i8.p0i8.i32(i8* <dest>, 16403 i8* <src>, 16404 i32 <len>, 16405 i32 <element_size>) 16406 declare void @llvm.memcpy.element.unordered.atomic.p0i8.p0i8.i64(i8* <dest>, 16407 i8* <src>, 16408 i64 <len>, 16409 i32 <element_size>) 16410 16411Overview: 16412""""""""" 16413 16414The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic is a specialization of the 16415'``llvm.memcpy.*``' intrinsic. It differs in that the ``dest`` and ``src`` are treated 16416as arrays with elements that are exactly ``element_size`` bytes, and the copy between 16417buffers uses a sequence of :ref:`unordered atomic <ordering>` load/store operations 16418that are a positive integer multiple of the ``element_size`` in size. 16419 16420Arguments: 16421"""""""""" 16422 16423The first three arguments are the same as they are in the :ref:`@llvm.memcpy <int_memcpy>` 16424intrinsic, with the added constraint that ``len`` is required to be a positive integer 16425multiple of the ``element_size``. If ``len`` is not a positive integer multiple of 16426``element_size``, then the behaviour of the intrinsic is undefined. 16427 16428``element_size`` must be a compile-time constant positive power of two no greater than 16429target-specific atomic access size limit. 16430 16431For each of the input pointers ``align`` parameter attribute must be specified. It 16432must be a power of two no less than the ``element_size``. Caller guarantees that 16433both the source and destination pointers are aligned to that boundary. 16434 16435Semantics: 16436"""""""""" 16437 16438The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic copies ``len`` bytes of 16439memory from the source location to the destination location. These locations are not 16440allowed to overlap. The memory copy is performed as a sequence of load/store operations 16441where each access is guaranteed to be a multiple of ``element_size`` bytes wide and 16442aligned at an ``element_size`` boundary. 16443 16444The order of the copy is unspecified. The same value may be read from the source 16445buffer many times, but only one write is issued to the destination buffer per 16446element. It is well defined to have concurrent reads and writes to both source and 16447destination provided those reads and writes are unordered atomic when specified. 16448 16449This intrinsic does not provide any additional ordering guarantees over those 16450provided by a set of unordered loads from the source location and stores to the 16451destination. 16452 16453Lowering: 16454""""""""" 16455 16456In the most general case call to the '``llvm.memcpy.element.unordered.atomic.*``' is 16457lowered to a call to the symbol ``__llvm_memcpy_element_unordered_atomic_*``. Where '*' 16458is replaced with an actual element size. 16459 16460Optimizer is allowed to inline memory copy when it's profitable to do so. 16461 16462'``llvm.memmove.element.unordered.atomic``' Intrinsic 16463^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16464 16465Syntax: 16466""""""" 16467 16468This is an overloaded intrinsic. You can use 16469``llvm.memmove.element.unordered.atomic`` on any integer bit width and for 16470different address spaces. Not all targets support all bit widths however. 16471 16472:: 16473 16474 declare void @llvm.memmove.element.unordered.atomic.p0i8.p0i8.i32(i8* <dest>, 16475 i8* <src>, 16476 i32 <len>, 16477 i32 <element_size>) 16478 declare void @llvm.memmove.element.unordered.atomic.p0i8.p0i8.i64(i8* <dest>, 16479 i8* <src>, 16480 i64 <len>, 16481 i32 <element_size>) 16482 16483Overview: 16484""""""""" 16485 16486The '``llvm.memmove.element.unordered.atomic.*``' intrinsic is a specialization 16487of the '``llvm.memmove.*``' intrinsic. It differs in that the ``dest`` and 16488``src`` are treated as arrays with elements that are exactly ``element_size`` 16489bytes, and the copy between buffers uses a sequence of 16490:ref:`unordered atomic <ordering>` load/store operations that are a positive 16491integer multiple of the ``element_size`` in size. 16492 16493Arguments: 16494"""""""""" 16495 16496The first three arguments are the same as they are in the 16497:ref:`@llvm.memmove <int_memmove>` intrinsic, with the added constraint that 16498``len`` is required to be a positive integer multiple of the ``element_size``. 16499If ``len`` is not a positive integer multiple of ``element_size``, then the 16500behaviour of the intrinsic is undefined. 16501 16502``element_size`` must be a compile-time constant positive power of two no 16503greater than a target-specific atomic access size limit. 16504 16505For each of the input pointers the ``align`` parameter attribute must be 16506specified. It must be a power of two no less than the ``element_size``. Caller 16507guarantees that both the source and destination pointers are aligned to that 16508boundary. 16509 16510Semantics: 16511"""""""""" 16512 16513The '``llvm.memmove.element.unordered.atomic.*``' intrinsic copies ``len`` bytes 16514of memory from the source location to the destination location. These locations 16515are allowed to overlap. The memory copy is performed as a sequence of load/store 16516operations where each access is guaranteed to be a multiple of ``element_size`` 16517bytes wide and aligned at an ``element_size`` boundary. 16518 16519The order of the copy is unspecified. The same value may be read from the source 16520buffer many times, but only one write is issued to the destination buffer per 16521element. It is well defined to have concurrent reads and writes to both source 16522and destination provided those reads and writes are unordered atomic when 16523specified. 16524 16525This intrinsic does not provide any additional ordering guarantees over those 16526provided by a set of unordered loads from the source location and stores to the 16527destination. 16528 16529Lowering: 16530""""""""" 16531 16532In the most general case call to the 16533'``llvm.memmove.element.unordered.atomic.*``' is lowered to a call to the symbol 16534``__llvm_memmove_element_unordered_atomic_*``. Where '*' is replaced with an 16535actual element size. 16536 16537The optimizer is allowed to inline the memory copy when it's profitable to do so. 16538 16539.. _int_memset_element_unordered_atomic: 16540 16541'``llvm.memset.element.unordered.atomic``' Intrinsic 16542^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16543 16544Syntax: 16545""""""" 16546 16547This is an overloaded intrinsic. You can use ``llvm.memset.element.unordered.atomic`` on 16548any integer bit width and for different address spaces. Not all targets 16549support all bit widths however. 16550 16551:: 16552 16553 declare void @llvm.memset.element.unordered.atomic.p0i8.i32(i8* <dest>, 16554 i8 <value>, 16555 i32 <len>, 16556 i32 <element_size>) 16557 declare void @llvm.memset.element.unordered.atomic.p0i8.i64(i8* <dest>, 16558 i8 <value>, 16559 i64 <len>, 16560 i32 <element_size>) 16561 16562Overview: 16563""""""""" 16564 16565The '``llvm.memset.element.unordered.atomic.*``' intrinsic is a specialization of the 16566'``llvm.memset.*``' intrinsic. It differs in that the ``dest`` is treated as an array 16567with elements that are exactly ``element_size`` bytes, and the assignment to that array 16568uses uses a sequence of :ref:`unordered atomic <ordering>` store operations 16569that are a positive integer multiple of the ``element_size`` in size. 16570 16571Arguments: 16572"""""""""" 16573 16574The first three arguments are the same as they are in the :ref:`@llvm.memset <int_memset>` 16575intrinsic, with the added constraint that ``len`` is required to be a positive integer 16576multiple of the ``element_size``. If ``len`` is not a positive integer multiple of 16577``element_size``, then the behaviour of the intrinsic is undefined. 16578 16579``element_size`` must be a compile-time constant positive power of two no greater than 16580target-specific atomic access size limit. 16581 16582The ``dest`` input pointer must have the ``align`` parameter attribute specified. It 16583must be a power of two no less than the ``element_size``. Caller guarantees that 16584the destination pointer is aligned to that boundary. 16585 16586Semantics: 16587"""""""""" 16588 16589The '``llvm.memset.element.unordered.atomic.*``' intrinsic sets the ``len`` bytes of 16590memory starting at the destination location to the given ``value``. The memory is 16591set with a sequence of store operations where each access is guaranteed to be a 16592multiple of ``element_size`` bytes wide and aligned at an ``element_size`` boundary. 16593 16594The order of the assignment is unspecified. Only one write is issued to the 16595destination buffer per element. It is well defined to have concurrent reads and 16596writes to the destination provided those reads and writes are unordered atomic 16597when specified. 16598 16599This intrinsic does not provide any additional ordering guarantees over those 16600provided by a set of unordered stores to the destination. 16601 16602Lowering: 16603""""""""" 16604 16605In the most general case call to the '``llvm.memset.element.unordered.atomic.*``' is 16606lowered to a call to the symbol ``__llvm_memset_element_unordered_atomic_*``. Where '*' 16607is replaced with an actual element size. 16608 16609The optimizer is allowed to inline the memory assignment when it's profitable to do so. 16610 16611Objective-C ARC Runtime Intrinsics 16612---------------------------------- 16613 16614LLVM provides intrinsics that lower to Objective-C ARC runtime entry points. 16615LLVM is aware of the semantics of these functions, and optimizes based on that 16616knowledge. You can read more about the details of Objective-C ARC `here 16617<https://clang.llvm.org/docs/AutomaticReferenceCounting.html>`_. 16618 16619'``llvm.objc.autorelease``' Intrinsic 16620^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16621 16622Syntax: 16623""""""" 16624:: 16625 16626 declare i8* @llvm.objc.autorelease(i8*) 16627 16628Lowering: 16629""""""""" 16630 16631Lowers to a call to `objc_autorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autorelease>`_. 16632 16633'``llvm.objc.autoreleasePoolPop``' Intrinsic 16634^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16635 16636Syntax: 16637""""""" 16638:: 16639 16640 declare void @llvm.objc.autoreleasePoolPop(i8*) 16641 16642Lowering: 16643""""""""" 16644 16645Lowers to a call to `objc_autoreleasePoolPop <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpop-void-pool>`_. 16646 16647'``llvm.objc.autoreleasePoolPush``' Intrinsic 16648^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16649 16650Syntax: 16651""""""" 16652:: 16653 16654 declare i8* @llvm.objc.autoreleasePoolPush() 16655 16656Lowering: 16657""""""""" 16658 16659Lowers to a call to `objc_autoreleasePoolPush <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpush-void>`_. 16660 16661'``llvm.objc.autoreleaseReturnValue``' Intrinsic 16662^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16663 16664Syntax: 16665""""""" 16666:: 16667 16668 declare i8* @llvm.objc.autoreleaseReturnValue(i8*) 16669 16670Lowering: 16671""""""""" 16672 16673Lowers to a call to `objc_autoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autoreleasereturnvalue>`_. 16674 16675'``llvm.objc.copyWeak``' Intrinsic 16676^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16677 16678Syntax: 16679""""""" 16680:: 16681 16682 declare void @llvm.objc.copyWeak(i8**, i8**) 16683 16684Lowering: 16685""""""""" 16686 16687Lowers to a call to `objc_copyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-copyweak-id-dest-id-src>`_. 16688 16689'``llvm.objc.destroyWeak``' Intrinsic 16690^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16691 16692Syntax: 16693""""""" 16694:: 16695 16696 declare void @llvm.objc.destroyWeak(i8**) 16697 16698Lowering: 16699""""""""" 16700 16701Lowers to a call to `objc_destroyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-destroyweak-id-object>`_. 16702 16703'``llvm.objc.initWeak``' Intrinsic 16704^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16705 16706Syntax: 16707""""""" 16708:: 16709 16710 declare i8* @llvm.objc.initWeak(i8**, i8*) 16711 16712Lowering: 16713""""""""" 16714 16715Lowers to a call to `objc_initWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-initweak>`_. 16716 16717'``llvm.objc.loadWeak``' Intrinsic 16718^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16719 16720Syntax: 16721""""""" 16722:: 16723 16724 declare i8* @llvm.objc.loadWeak(i8**) 16725 16726Lowering: 16727""""""""" 16728 16729Lowers to a call to `objc_loadWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweak>`_. 16730 16731'``llvm.objc.loadWeakRetained``' Intrinsic 16732^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16733 16734Syntax: 16735""""""" 16736:: 16737 16738 declare i8* @llvm.objc.loadWeakRetained(i8**) 16739 16740Lowering: 16741""""""""" 16742 16743Lowers to a call to `objc_loadWeakRetained <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweakretained>`_. 16744 16745'``llvm.objc.moveWeak``' Intrinsic 16746^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16747 16748Syntax: 16749""""""" 16750:: 16751 16752 declare void @llvm.objc.moveWeak(i8**, i8**) 16753 16754Lowering: 16755""""""""" 16756 16757Lowers to a call to `objc_moveWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-moveweak-id-dest-id-src>`_. 16758 16759'``llvm.objc.release``' Intrinsic 16760^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16761 16762Syntax: 16763""""""" 16764:: 16765 16766 declare void @llvm.objc.release(i8*) 16767 16768Lowering: 16769""""""""" 16770 16771Lowers to a call to `objc_release <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-release-id-value>`_. 16772 16773'``llvm.objc.retain``' Intrinsic 16774^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16775 16776Syntax: 16777""""""" 16778:: 16779 16780 declare i8* @llvm.objc.retain(i8*) 16781 16782Lowering: 16783""""""""" 16784 16785Lowers to a call to `objc_retain <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retain>`_. 16786 16787'``llvm.objc.retainAutorelease``' Intrinsic 16788^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16789 16790Syntax: 16791""""""" 16792:: 16793 16794 declare i8* @llvm.objc.retainAutorelease(i8*) 16795 16796Lowering: 16797""""""""" 16798 16799Lowers to a call to `objc_retainAutorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautorelease>`_. 16800 16801'``llvm.objc.retainAutoreleaseReturnValue``' Intrinsic 16802^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16803 16804Syntax: 16805""""""" 16806:: 16807 16808 declare i8* @llvm.objc.retainAutoreleaseReturnValue(i8*) 16809 16810Lowering: 16811""""""""" 16812 16813Lowers to a call to `objc_retainAutoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasereturnvalue>`_. 16814 16815'``llvm.objc.retainAutoreleasedReturnValue``' Intrinsic 16816^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16817 16818Syntax: 16819""""""" 16820:: 16821 16822 declare i8* @llvm.objc.retainAutoreleasedReturnValue(i8*) 16823 16824Lowering: 16825""""""""" 16826 16827Lowers to a call to `objc_retainAutoreleasedReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasedreturnvalue>`_. 16828 16829'``llvm.objc.retainBlock``' Intrinsic 16830^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16831 16832Syntax: 16833""""""" 16834:: 16835 16836 declare i8* @llvm.objc.retainBlock(i8*) 16837 16838Lowering: 16839""""""""" 16840 16841Lowers to a call to `objc_retainBlock <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainblock>`_. 16842 16843'``llvm.objc.storeStrong``' Intrinsic 16844^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16845 16846Syntax: 16847""""""" 16848:: 16849 16850 declare void @llvm.objc.storeStrong(i8**, i8*) 16851 16852Lowering: 16853""""""""" 16854 16855Lowers to a call to `objc_storeStrong <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-storestrong-id-object-id-value>`_. 16856 16857'``llvm.objc.storeWeak``' Intrinsic 16858^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16859 16860Syntax: 16861""""""" 16862:: 16863 16864 declare i8* @llvm.objc.storeWeak(i8**, i8*) 16865 16866Lowering: 16867""""""""" 16868 16869Lowers to a call to `objc_storeWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-storeweak>`_. 16870