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 global variable or function *declaration* to have any 276linkage type other 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 tailcc, 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 preserved 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"``tailcc``" - Tail callable calling convention 440 This calling convention ensures that calls in tail position will always be 441 tail call optimized. This calling convention is equivalent to fastcc, 442 except for an additional guarantee that tail calls will be produced 443 whenever possible. `Tail calls can only be optimized when this, the fastcc, 444 the GHC or the HiPE convention is used. <CodeGenerator.html#id80>`_ This 445 calling convention does not support varargs and requires the prototype of 446 all callees to exactly match the prototype of the function definition. 447"``cfguard_checkcc``" - Windows Control Flow Guard (Check mechanism) 448 This calling convention is used for the Control Flow Guard check function, 449 calls to which can be inserted before indirect calls to check that the call 450 target is a valid function address. The check function has no return value, 451 but it will trigger an OS-level error if the address is not a valid target. 452 The set of registers preserved by the check function, and the register 453 containing the target address are architecture-specific. 454 455 - On X86 the target address is passed in ECX. 456 - On ARM the target address is passed in R0. 457 - On AArch64 the target address is passed in X15. 458"``cc <n>``" - Numbered convention 459 Any calling convention may be specified by number, allowing 460 target-specific calling conventions to be used. Target specific 461 calling conventions start at 64. 462 463More calling conventions can be added/defined on an as-needed basis, to 464support Pascal conventions or any other well-known target-independent 465convention. 466 467.. _visibilitystyles: 468 469Visibility Styles 470----------------- 471 472All Global Variables and Functions have one of the following visibility 473styles: 474 475"``default``" - Default style 476 On targets that use the ELF object file format, default visibility 477 means that the declaration is visible to other modules and, in 478 shared libraries, means that the declared entity may be overridden. 479 On Darwin, default visibility means that the declaration is visible 480 to other modules. Default visibility corresponds to "external 481 linkage" in the language. 482"``hidden``" - Hidden style 483 Two declarations of an object with hidden visibility refer to the 484 same object if they are in the same shared object. Usually, hidden 485 visibility indicates that the symbol will not be placed into the 486 dynamic symbol table, so no other module (executable or shared 487 library) can reference it directly. 488"``protected``" - Protected style 489 On ELF, protected visibility indicates that the symbol will be 490 placed in the dynamic symbol table, but that references within the 491 defining module will bind to the local symbol. That is, the symbol 492 cannot be overridden by another module. 493 494A symbol with ``internal`` or ``private`` linkage must have ``default`` 495visibility. 496 497.. _dllstorageclass: 498 499DLL Storage Classes 500------------------- 501 502All Global Variables, Functions and Aliases can have one of the following 503DLL storage class: 504 505``dllimport`` 506 "``dllimport``" causes the compiler to reference a function or variable via 507 a global pointer to a pointer that is set up by the DLL exporting the 508 symbol. On Microsoft Windows targets, the pointer name is formed by 509 combining ``__imp_`` and the function or variable name. 510``dllexport`` 511 "``dllexport``" causes the compiler to provide a global pointer to a pointer 512 in a DLL, so that it can be referenced with the ``dllimport`` attribute. On 513 Microsoft Windows targets, the pointer name is formed by combining 514 ``__imp_`` and the function or variable name. Since this storage class 515 exists for defining a dll interface, the compiler, assembler and linker know 516 it is externally referenced and must refrain from deleting the symbol. 517 518.. _tls_model: 519 520Thread Local Storage Models 521--------------------------- 522 523A variable may be defined as ``thread_local``, which means that it will 524not be shared by threads (each thread will have a separated copy of the 525variable). Not all targets support thread-local variables. Optionally, a 526TLS model may be specified: 527 528``localdynamic`` 529 For variables that are only used within the current shared library. 530``initialexec`` 531 For variables in modules that will not be loaded dynamically. 532``localexec`` 533 For variables defined in the executable and only used within it. 534 535If no explicit model is given, the "general dynamic" model is used. 536 537The models correspond to the ELF TLS models; see `ELF Handling For 538Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for 539more information on under which circumstances the different models may 540be used. The target may choose a different TLS model if the specified 541model is not supported, or if a better choice of model can be made. 542 543A model can also be specified in an alias, but then it only governs how 544the alias is accessed. It will not have any effect in the aliasee. 545 546For platforms without linker support of ELF TLS model, the -femulated-tls 547flag can be used to generate GCC compatible emulated TLS code. 548 549.. _runtime_preemption_model: 550 551Runtime Preemption Specifiers 552----------------------------- 553 554Global variables, functions and aliases may have an optional runtime preemption 555specifier. If a preemption specifier isn't given explicitly, then a 556symbol is assumed to be ``dso_preemptable``. 557 558``dso_preemptable`` 559 Indicates that the function or variable may be replaced by a symbol from 560 outside the linkage unit at runtime. 561 562``dso_local`` 563 The compiler may assume that a function or variable marked as ``dso_local`` 564 will resolve to a symbol within the same linkage unit. Direct access will 565 be generated even if the definition is not within this compilation unit. 566 567.. _namedtypes: 568 569Structure Types 570--------------- 571 572LLVM IR allows you to specify both "identified" and "literal" :ref:`structure 573types <t_struct>`. Literal types are uniqued structurally, but identified types 574are never uniqued. An :ref:`opaque structural type <t_opaque>` can also be used 575to forward declare a type that is not yet available. 576 577An example of an identified structure specification is: 578 579.. code-block:: llvm 580 581 %mytype = type { %mytype*, i32 } 582 583Prior to the LLVM 3.0 release, identified types were structurally uniqued. Only 584literal types are uniqued in recent versions of LLVM. 585 586.. _nointptrtype: 587 588Non-Integral Pointer Type 589------------------------- 590 591Note: non-integral pointer types are a work in progress, and they should be 592considered experimental at this time. 593 594LLVM IR optionally allows the frontend to denote pointers in certain address 595spaces as "non-integral" via the :ref:`datalayout string<langref_datalayout>`. 596Non-integral pointer types represent pointers that have an *unspecified* bitwise 597representation; that is, the integral representation may be target dependent or 598unstable (not backed by a fixed integer). 599 600``inttoptr`` instructions converting integers to non-integral pointer types are 601ill-typed, and so are ``ptrtoint`` instructions converting values of 602non-integral pointer types to integers. Vector versions of said instructions 603are ill-typed as well. 604 605.. _globalvars: 606 607Global Variables 608---------------- 609 610Global variables define regions of memory allocated at compilation time 611instead of run-time. 612 613Global variable definitions must be initialized. 614 615Global variables in other translation units can also be declared, in which 616case they don't have an initializer. 617 618Global variables can optionally specify a :ref:`linkage type <linkage>`. 619 620Either global variable definitions or declarations may have an explicit section 621to be placed in and may have an optional explicit alignment specified. If there 622is a mismatch between the explicit or inferred section information for the 623variable declaration and its definition the resulting behavior is undefined. 624 625A variable may be defined as a global ``constant``, which indicates that 626the contents of the variable will **never** be modified (enabling better 627optimization, allowing the global data to be placed in the read-only 628section of an executable, etc). Note that variables that need runtime 629initialization cannot be marked ``constant`` as there is a store to the 630variable. 631 632LLVM explicitly allows *declarations* of global variables to be marked 633constant, even if the final definition of the global is not. This 634capability can be used to enable slightly better optimization of the 635program, but requires the language definition to guarantee that 636optimizations based on the 'constantness' are valid for the translation 637units that do not include the definition. 638 639As SSA values, global variables define pointer values that are in scope 640(i.e. they dominate) all basic blocks in the program. Global variables 641always define a pointer to their "content" type because they describe a 642region of memory, and all memory objects in LLVM are accessed through 643pointers. 644 645Global variables can be marked with ``unnamed_addr`` which indicates 646that the address is not significant, only the content. Constants marked 647like this can be merged with other constants if they have the same 648initializer. Note that a constant with significant address *can* be 649merged with a ``unnamed_addr`` constant, the result being a constant 650whose address is significant. 651 652If the ``local_unnamed_addr`` attribute is given, the address is known to 653not be significant within the module. 654 655A global variable may be declared to reside in a target-specific 656numbered address space. For targets that support them, address spaces 657may affect how optimizations are performed and/or what target 658instructions are used to access the variable. The default address space 659is zero. The address space qualifier must precede any other attributes. 660 661LLVM allows an explicit section to be specified for globals. If the 662target supports it, it will emit globals to the section specified. 663Additionally, the global can placed in a comdat if the target has the necessary 664support. 665 666External declarations may have an explicit section specified. Section 667information is retained in LLVM IR for targets that make use of this 668information. Attaching section information to an external declaration is an 669assertion that its definition is located in the specified section. If the 670definition is located in a different section, the behavior is undefined. 671 672By default, global initializers are optimized by assuming that global 673variables defined within the module are not modified from their 674initial values before the start of the global initializer. This is 675true even for variables potentially accessible from outside the 676module, including those with external linkage or appearing in 677``@llvm.used`` or dllexported variables. This assumption may be suppressed 678by marking the variable with ``externally_initialized``. 679 680An explicit alignment may be specified for a global, which must be a 681power of 2. If not present, or if the alignment is set to zero, the 682alignment of the global is set by the target to whatever it feels 683convenient. If an explicit alignment is specified, the global is forced 684to have exactly that alignment. Targets and optimizers are not allowed 685to over-align the global if the global has an assigned section. In this 686case, the extra alignment could be observable: for example, code could 687assume that the globals are densely packed in their section and try to 688iterate over them as an array, alignment padding would break this 689iteration. The maximum alignment is ``1 << 29``. 690 691For global variables declarations, as well as definitions that may be 692replaced at link time (``linkonce``, ``weak``, ``extern_weak`` and ``common`` 693linkage types), LLVM makes no assumptions about the allocation size of the 694variables, except that they may not overlap. The alignment of a global variable 695declaration or replaceable definition must not be greater than the alignment of 696the definition it resolves to. 697 698Globals can also have a :ref:`DLL storage class <dllstorageclass>`, 699an optional :ref:`runtime preemption specifier <runtime_preemption_model>`, 700an optional :ref:`global attributes <glattrs>` and 701an optional list of attached :ref:`metadata <metadata>`. 702 703Variables and aliases can have a 704:ref:`Thread Local Storage Model <tls_model>`. 705 706:ref:`Scalable vectors <t_vector>` cannot be global variables or members of 707arrays because their size is unknown at compile time. They are allowed in 708structs to facilitate intrinsics returning multiple values. Structs containing 709scalable vectors cannot be used in loads, stores, allocas, or GEPs. 710 711Syntax:: 712 713 @<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility] 714 [DLLStorageClass] [ThreadLocal] 715 [(unnamed_addr|local_unnamed_addr)] [AddrSpace] 716 [ExternallyInitialized] 717 <global | constant> <Type> [<InitializerConstant>] 718 [, section "name"] [, comdat [($name)]] 719 [, align <Alignment>] (, !name !N)* 720 721For example, the following defines a global in a numbered address space 722with an initializer, section, and alignment: 723 724.. code-block:: llvm 725 726 @G = addrspace(5) constant float 1.0, section "foo", align 4 727 728The following example just declares a global variable 729 730.. code-block:: llvm 731 732 @G = external global i32 733 734The following example defines a thread-local global with the 735``initialexec`` TLS model: 736 737.. code-block:: llvm 738 739 @G = thread_local(initialexec) global i32 0, align 4 740 741.. _functionstructure: 742 743Functions 744--------- 745 746LLVM function definitions consist of the "``define``" keyword, an 747optional :ref:`linkage type <linkage>`, an optional :ref:`runtime preemption 748specifier <runtime_preemption_model>`, an optional :ref:`visibility 749style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, 750an optional :ref:`calling convention <callingconv>`, 751an optional ``unnamed_addr`` attribute, a return type, an optional 752:ref:`parameter attribute <paramattrs>` for the return type, a function 753name, a (possibly empty) argument list (each with optional :ref:`parameter 754attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`, 755an optional address space, an optional section, an optional alignment, 756an optional :ref:`comdat <langref_comdats>`, 757an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`, 758an optional :ref:`prologue <prologuedata>`, 759an optional :ref:`personality <personalityfn>`, 760an optional list of attached :ref:`metadata <metadata>`, 761an opening curly brace, a list of basic blocks, and a closing curly brace. 762 763LLVM function declarations consist of the "``declare``" keyword, an 764optional :ref:`linkage type <linkage>`, an optional :ref:`visibility style 765<visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, an 766optional :ref:`calling convention <callingconv>`, an optional ``unnamed_addr`` 767or ``local_unnamed_addr`` attribute, an optional address space, a return type, 768an optional :ref:`parameter attribute <paramattrs>` for the return type, a function name, a possibly 769empty list of arguments, an optional alignment, an optional :ref:`garbage 770collector name <gc>`, an optional :ref:`prefix <prefixdata>`, and an optional 771:ref:`prologue <prologuedata>`. 772 773A function definition contains a list of basic blocks, forming the CFG (Control 774Flow Graph) for the function. Each basic block may optionally start with a label 775(giving the basic block a symbol table entry), contains a list of instructions, 776and ends with a :ref:`terminator <terminators>` instruction (such as a branch or 777function return). If an explicit label name is not provided, a block is assigned 778an implicit numbered label, using the next value from the same counter as used 779for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a 780function entry block does not have an explicit label, it will be assigned label 781"%0", then the first unnamed temporary in that block will be "%1", etc. If a 782numeric label is explicitly specified, it must match the numeric label that 783would be used implicitly. 784 785The first basic block in a function is special in two ways: it is 786immediately executed on entrance to the function, and it is not allowed 787to have predecessor basic blocks (i.e. there can not be any branches to 788the entry block of a function). Because the block can have no 789predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`. 790 791LLVM allows an explicit section to be specified for functions. If the 792target supports it, it will emit functions to the section specified. 793Additionally, the function can be placed in a COMDAT. 794 795An explicit alignment may be specified for a function. If not present, 796or if the alignment is set to zero, the alignment of the function is set 797by the target to whatever it feels convenient. If an explicit alignment 798is specified, the function is forced to have at least that much 799alignment. All alignments must be a power of 2. 800 801If the ``unnamed_addr`` attribute is given, the address is known to not 802be significant and two identical functions can be merged. 803 804If the ``local_unnamed_addr`` attribute is given, the address is known to 805not be significant within the module. 806 807If an explicit address space is not given, it will default to the program 808address space from the :ref:`datalayout string<langref_datalayout>`. 809 810Syntax:: 811 812 define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass] 813 [cconv] [ret attrs] 814 <ResultType> @<FunctionName> ([argument list]) 815 [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs] 816 [section "name"] [comdat [($name)]] [align N] [gc] [prefix Constant] 817 [prologue Constant] [personality Constant] (!name !N)* { ... } 818 819The argument list is a comma separated sequence of arguments where each 820argument is of the following form: 821 822Syntax:: 823 824 <type> [parameter Attrs] [name] 825 826 827.. _langref_aliases: 828 829Aliases 830------- 831 832Aliases, unlike function or variables, don't create any new data. They 833are just a new symbol and metadata for an existing position. 834 835Aliases have a name and an aliasee that is either a global value or a 836constant expression. 837 838Aliases may have an optional :ref:`linkage type <linkage>`, an optional 839:ref:`runtime preemption specifier <runtime_preemption_model>`, an optional 840:ref:`visibility style <visibility>`, an optional :ref:`DLL storage class 841<dllstorageclass>` and an optional :ref:`tls model <tls_model>`. 842 843Syntax:: 844 845 @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee> 846 847The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``, 848``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers 849might not correctly handle dropping a weak symbol that is aliased. 850 851Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as 852the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point 853to the same content. 854 855If the ``local_unnamed_addr`` attribute is given, the address is known to 856not be significant within the module. 857 858Since aliases are only a second name, some restrictions apply, of which 859some can only be checked when producing an object file: 860 861* The expression defining the aliasee must be computable at assembly 862 time. Since it is just a name, no relocations can be used. 863 864* No alias in the expression can be weak as the possibility of the 865 intermediate alias being overridden cannot be represented in an 866 object file. 867 868* No global value in the expression can be a declaration, since that 869 would require a relocation, which is not possible. 870 871.. _langref_ifunc: 872 873IFuncs 874------- 875 876IFuncs, like as aliases, don't create any new data or func. They are just a new 877symbol that dynamic linker resolves at runtime by calling a resolver function. 878 879IFuncs have a name and a resolver that is a function called by dynamic linker 880that returns address of another function associated with the name. 881 882IFunc may have an optional :ref:`linkage type <linkage>` and an optional 883:ref:`visibility style <visibility>`. 884 885Syntax:: 886 887 @<Name> = [Linkage] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver> 888 889 890.. _langref_comdats: 891 892Comdats 893------- 894 895Comdat IR provides access to COFF and ELF object file COMDAT functionality. 896 897Comdats have a name which represents the COMDAT key. All global objects that 898specify this key will only end up in the final object file if the linker chooses 899that key over some other key. Aliases are placed in the same COMDAT that their 900aliasee computes to, if any. 901 902Comdats have a selection kind to provide input on how the linker should 903choose between keys in two different object files. 904 905Syntax:: 906 907 $<Name> = comdat SelectionKind 908 909The selection kind must be one of the following: 910 911``any`` 912 The linker may choose any COMDAT key, the choice is arbitrary. 913``exactmatch`` 914 The linker may choose any COMDAT key but the sections must contain the 915 same data. 916``largest`` 917 The linker will choose the section containing the largest COMDAT key. 918``noduplicates`` 919 The linker requires that only section with this COMDAT key exist. 920``samesize`` 921 The linker may choose any COMDAT key but the sections must contain the 922 same amount of data. 923 924Note that XCOFF and the Mach-O platform don't support COMDATs, and ELF and 925WebAssembly only support ``any`` as a selection kind. 926 927Here is an example of a COMDAT group where a function will only be selected if 928the COMDAT key's section is the largest: 929 930.. code-block:: text 931 932 $foo = comdat largest 933 @foo = global i32 2, comdat($foo) 934 935 define void @bar() comdat($foo) { 936 ret void 937 } 938 939As a syntactic sugar the ``$name`` can be omitted if the name is the same as 940the global name: 941 942.. code-block:: llvm 943 944 $foo = comdat any 945 @foo = global i32 2, comdat 946 947 948In a COFF object file, this will create a COMDAT section with selection kind 949``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol 950and another COMDAT section with selection kind 951``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT 952section and contains the contents of the ``@bar`` symbol. 953 954There are some restrictions on the properties of the global object. 955It, or an alias to it, must have the same name as the COMDAT group when 956targeting COFF. 957The contents and size of this object may be used during link-time to determine 958which COMDAT groups get selected depending on the selection kind. 959Because the name of the object must match the name of the COMDAT group, the 960linkage of the global object must not be local; local symbols can get renamed 961if a collision occurs in the symbol table. 962 963The combined use of COMDATS and section attributes may yield surprising results. 964For example: 965 966.. code-block:: llvm 967 968 $foo = comdat any 969 $bar = comdat any 970 @g1 = global i32 42, section "sec", comdat($foo) 971 @g2 = global i32 42, section "sec", comdat($bar) 972 973From the object file perspective, this requires the creation of two sections 974with the same name. This is necessary because both globals belong to different 975COMDAT groups and COMDATs, at the object file level, are represented by 976sections. 977 978Note that certain IR constructs like global variables and functions may 979create COMDATs in the object file in addition to any which are specified using 980COMDAT IR. This arises when the code generator is configured to emit globals 981in individual sections (e.g. when `-data-sections` or `-function-sections` 982is supplied to `llc`). 983 984.. _namedmetadatastructure: 985 986Named Metadata 987-------------- 988 989Named metadata is a collection of metadata. :ref:`Metadata 990nodes <metadata>` (but not metadata strings) are the only valid 991operands for a named metadata. 992 993#. Named metadata are represented as a string of characters with the 994 metadata prefix. The rules for metadata names are the same as for 995 identifiers, but quoted names are not allowed. ``"\xx"`` type escapes 996 are still valid, which allows any character to be part of a name. 997 998Syntax:: 999 1000 ; Some unnamed metadata nodes, which are referenced by the named metadata. 1001 !0 = !{!"zero"} 1002 !1 = !{!"one"} 1003 !2 = !{!"two"} 1004 ; A named metadata. 1005 !name = !{!0, !1, !2} 1006 1007.. _paramattrs: 1008 1009Parameter Attributes 1010-------------------- 1011 1012The return type and each parameter of a function type may have a set of 1013*parameter attributes* associated with them. Parameter attributes are 1014used to communicate additional information about the result or 1015parameters of a function. Parameter attributes are considered to be part 1016of the function, not of the function type, so functions with different 1017parameter attributes can have the same function type. 1018 1019Parameter attributes are simple keywords that follow the type specified. 1020If multiple parameter attributes are needed, they are space separated. 1021For example: 1022 1023.. code-block:: llvm 1024 1025 declare i32 @printf(i8* noalias nocapture, ...) 1026 declare i32 @atoi(i8 zeroext) 1027 declare signext i8 @returns_signed_char() 1028 1029Note that any attributes for the function result (``nounwind``, 1030``readonly``) come immediately after the argument list. 1031 1032Currently, only the following parameter attributes are defined: 1033 1034``zeroext`` 1035 This indicates to the code generator that the parameter or return 1036 value should be zero-extended to the extent required by the target's 1037 ABI by the caller (for a parameter) or the callee (for a return value). 1038``signext`` 1039 This indicates to the code generator that the parameter or return 1040 value should be sign-extended to the extent required by the target's 1041 ABI (which is usually 32-bits) by the caller (for a parameter) or 1042 the callee (for a return value). 1043``inreg`` 1044 This indicates that this parameter or return value should be treated 1045 in a special target-dependent fashion while emitting code for 1046 a function call or return (usually, by putting it in a register as 1047 opposed to memory, though some targets use it to distinguish between 1048 two different kinds of registers). Use of this attribute is 1049 target-specific. 1050``byval(<ty>)`` 1051 This indicates that the pointer parameter should really be passed by 1052 value to the function. The attribute implies that a hidden copy of 1053 the pointee is made between the caller and the callee, so the callee 1054 is unable to modify the value in the caller. This attribute is only 1055 valid on LLVM pointer arguments. It is generally used to pass 1056 structs and arrays by value, but is also valid on pointers to 1057 scalars. The copy is considered to belong to the caller not the 1058 callee (for example, ``readonly`` functions should not write to 1059 ``byval`` parameters). This is not a valid attribute for return 1060 values. 1061 1062 The byval type argument indicates the in-memory value type, and 1063 must be the same as the pointee type of the argument. 1064 1065 The byval attribute also supports specifying an alignment with the 1066 align attribute. It indicates the alignment of the stack slot to 1067 form and the known alignment of the pointer specified to the call 1068 site. If the alignment is not specified, then the code generator 1069 makes a target-specific assumption. 1070 1071.. _attr_byref: 1072 1073``byref(<ty>)`` 1074 1075 The ``byref`` argument attribute allows specifying the pointee 1076 memory type of an argument. This is similar to ``byval``, but does 1077 not imply a copy is made anywhere, or that the argument is passed 1078 on the stack. This implies the pointer is dereferenceable up to 1079 the storage size of the type. 1080 1081 It is not generally permissible to introduce a write to an 1082 ``byref`` pointer. The pointer may have any address space and may 1083 be read only. 1084 1085 This is not a valid attribute for return values. 1086 1087 The alignment for an ``byref`` parameter can be explicitly 1088 specified by combining it with the ``align`` attribute, similar to 1089 ``byval``. If the alignment is not specified, then the code generator 1090 makes a target-specific assumption. 1091 1092 This is intended for representing ABI constraints, and is not 1093 intended to be inferred for optimization use. 1094 1095.. _attr_preallocated: 1096 1097``preallocated(<ty>)`` 1098 This indicates that the pointer parameter should really be passed by 1099 value to the function, and that the pointer parameter's pointee has 1100 already been initialized before the call instruction. This attribute 1101 is only valid on LLVM pointer arguments. The argument must be the value 1102 returned by the appropriate 1103 :ref:`llvm.call.preallocated.arg<int_call_preallocated_arg>` on non 1104 ``musttail`` calls, or the corresponding caller parameter in ``musttail`` 1105 calls, although it is ignored during codegen. 1106 1107 A non ``musttail`` function call with a ``preallocated`` attribute in 1108 any parameter must have a ``"preallocated"`` operand bundle. A ``musttail`` 1109 function call cannot have a ``"preallocated"`` operand bundle. 1110 1111 The preallocated attribute requires a type argument, which must be 1112 the same as the pointee type of the argument. 1113 1114 The preallocated attribute also supports specifying an alignment with the 1115 align attribute. It indicates the alignment of the stack slot to 1116 form and the known alignment of the pointer specified to the call 1117 site. If the alignment is not specified, then the code generator 1118 makes a target-specific assumption. 1119 1120.. _attr_inalloca: 1121 1122``inalloca(<ty>)`` 1123 1124 The ``inalloca`` argument attribute allows the caller to take the 1125 address of outgoing stack arguments. An ``inalloca`` argument must 1126 be a pointer to stack memory produced by an ``alloca`` instruction. 1127 The alloca, or argument allocation, must also be tagged with the 1128 inalloca keyword. Only the last argument may have the ``inalloca`` 1129 attribute, and that argument is guaranteed to be passed in memory. 1130 1131 An argument allocation may be used by a call at most once because 1132 the call may deallocate it. The ``inalloca`` attribute cannot be 1133 used in conjunction with other attributes that affect argument 1134 storage, like ``inreg``, ``nest``, ``sret``, or ``byval``. The 1135 ``inalloca`` attribute also disables LLVM's implicit lowering of 1136 large aggregate return values, which means that frontend authors 1137 must lower them with ``sret`` pointers. 1138 1139 When the call site is reached, the argument allocation must have 1140 been the most recent stack allocation that is still live, or the 1141 behavior is undefined. It is possible to allocate additional stack 1142 space after an argument allocation and before its call site, but it 1143 must be cleared off with :ref:`llvm.stackrestore 1144 <int_stackrestore>`. 1145 1146 The inalloca attribute requires a type argument, which must be the 1147 same as the pointee type of the argument. 1148 1149 See :doc:`InAlloca` for more information on how to use this 1150 attribute. 1151 1152``sret(<ty>)`` 1153 This indicates that the pointer parameter specifies the address of a 1154 structure that is the return value of the function in the source 1155 program. This pointer must be guaranteed by the caller to be valid: 1156 loads and stores to the structure may be assumed by the callee not 1157 to trap and to be properly aligned. This is not a valid attribute 1158 for return values. 1159 1160 The sret type argument specifies the in memory type, which must be 1161 the same as the pointee type of the argument. 1162 1163.. _attr_align: 1164 1165``align <n>`` or ``align(<n>)`` 1166 This indicates that the pointer value has the specified alignment. 1167 If the pointer value does not have the specified alignment, 1168 :ref:`poison value <poisonvalues>` is returned or passed instead. The 1169 ``align`` attribute should be combined with the ``noundef`` attribute to 1170 ensure a pointer is aligned, or otherwise the behavior is undefined. Note 1171 that ``align 1`` has no effect on non-byval, non-preallocated arguments. 1172 1173 Note that this attribute has additional semantics when combined with the 1174 ``byval`` or ``preallocated`` attribute, which are documented there. 1175 1176.. _noalias: 1177 1178``noalias`` 1179 This indicates that memory locations accessed via pointer values 1180 :ref:`based <pointeraliasing>` on the argument or return value are not also 1181 accessed, during the execution of the function, via pointer values not 1182 *based* on the argument or return value. This guarantee only holds for 1183 memory locations that are *modified*, by any means, during the execution of 1184 the function. The attribute on a return value also has additional semantics 1185 described below. The caller shares the responsibility with the callee for 1186 ensuring that these requirements are met. For further details, please see 1187 the discussion of the NoAlias response in :ref:`alias analysis <Must, May, 1188 or No>`. 1189 1190 Note that this definition of ``noalias`` is intentionally similar 1191 to the definition of ``restrict`` in C99 for function arguments. 1192 1193 For function return values, C99's ``restrict`` is not meaningful, 1194 while LLVM's ``noalias`` is. Furthermore, the semantics of the ``noalias`` 1195 attribute on return values are stronger than the semantics of the attribute 1196 when used on function arguments. On function return values, the ``noalias`` 1197 attribute indicates that the function acts like a system memory allocation 1198 function, returning a pointer to allocated storage disjoint from the 1199 storage for any other object accessible to the caller. 1200 1201.. _nocapture: 1202 1203``nocapture`` 1204 This indicates that the callee does not :ref:`capture <pointercapture>` the 1205 pointer. This is not a valid attribute for return values. 1206 This attribute applies only to the particular copy of the pointer passed in 1207 this argument. A caller could pass two copies of the same pointer with one 1208 being annotated nocapture and the other not, and the callee could validly 1209 capture through the non annotated parameter. 1210 1211.. code-block:: llvm 1212 1213 define void @f(i8* nocapture %a, i8* %b) { 1214 ; (capture %b) 1215 } 1216 1217 call void @f(i8* @glb, i8* @glb) ; well-defined 1218 1219``nofree`` 1220 This indicates that callee does not free the pointer argument. This is not 1221 a valid attribute for return values. 1222 1223.. _nest: 1224 1225``nest`` 1226 This indicates that the pointer parameter can be excised using the 1227 :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid 1228 attribute for return values and can only be applied to one parameter. 1229 1230``returned`` 1231 This indicates that the function always returns the argument as its return 1232 value. This is a hint to the optimizer and code generator used when 1233 generating the caller, allowing value propagation, tail call optimization, 1234 and omission of register saves and restores in some cases; it is not 1235 checked or enforced when generating the callee. The parameter and the 1236 function return type must be valid operands for the 1237 :ref:`bitcast instruction <i_bitcast>`. This is not a valid attribute for 1238 return values and can only be applied to one parameter. 1239 1240``nonnull`` 1241 This indicates that the parameter or return pointer is not null. This 1242 attribute may only be applied to pointer typed parameters. This is not 1243 checked or enforced by LLVM; if the parameter or return pointer is null, 1244 :ref:`poison value <poisonvalues>` is returned or passed instead. 1245 The ``nonnull`` attribute should be combined with the ``noundef`` attribute 1246 to ensure a pointer is not null or otherwise the behavior is undefined. 1247 1248``dereferenceable(<n>)`` 1249 This indicates that the parameter or return pointer is dereferenceable. This 1250 attribute may only be applied to pointer typed parameters. A pointer that 1251 is dereferenceable can be loaded from speculatively without a risk of 1252 trapping. The number of bytes known to be dereferenceable must be provided 1253 in parentheses. It is legal for the number of bytes to be less than the 1254 size of the pointee type. The ``nonnull`` attribute does not imply 1255 dereferenceability (consider a pointer to one element past the end of an 1256 array), however ``dereferenceable(<n>)`` does imply ``nonnull`` in 1257 ``addrspace(0)`` (which is the default address space), except if the 1258 ``null_pointer_is_valid`` function attribute is present. 1259 ``n`` should be a positive number. The pointer should be well defined, 1260 otherwise it is undefined behavior. This means ``dereferenceable(<n>)`` 1261 implies ``noundef``. 1262 1263``dereferenceable_or_null(<n>)`` 1264 This indicates that the parameter or return value isn't both 1265 non-null and non-dereferenceable (up to ``<n>`` bytes) at the same 1266 time. All non-null pointers tagged with 1267 ``dereferenceable_or_null(<n>)`` are ``dereferenceable(<n>)``. 1268 For address space 0 ``dereferenceable_or_null(<n>)`` implies that 1269 a pointer is exactly one of ``dereferenceable(<n>)`` or ``null``, 1270 and in other address spaces ``dereferenceable_or_null(<n>)`` 1271 implies that a pointer is at least one of ``dereferenceable(<n>)`` 1272 or ``null`` (i.e. it may be both ``null`` and 1273 ``dereferenceable(<n>)``). This attribute may only be applied to 1274 pointer typed parameters. 1275 1276``swiftself`` 1277 This indicates that the parameter is the self/context parameter. This is not 1278 a valid attribute for return values and can only be applied to one 1279 parameter. 1280 1281``swifterror`` 1282 This attribute is motivated to model and optimize Swift error handling. It 1283 can be applied to a parameter with pointer to pointer type or a 1284 pointer-sized alloca. At the call site, the actual argument that corresponds 1285 to a ``swifterror`` parameter has to come from a ``swifterror`` alloca or 1286 the ``swifterror`` parameter of the caller. A ``swifterror`` value (either 1287 the parameter or the alloca) can only be loaded and stored from, or used as 1288 a ``swifterror`` argument. This is not a valid attribute for return values 1289 and can only be applied to one parameter. 1290 1291 These constraints allow the calling convention to optimize access to 1292 ``swifterror`` variables by associating them with a specific register at 1293 call boundaries rather than placing them in memory. Since this does change 1294 the calling convention, a function which uses the ``swifterror`` attribute 1295 on a parameter is not ABI-compatible with one which does not. 1296 1297 These constraints also allow LLVM to assume that a ``swifterror`` argument 1298 does not alias any other memory visible within a function and that a 1299 ``swifterror`` alloca passed as an argument does not escape. 1300 1301``immarg`` 1302 This indicates the parameter is required to be an immediate 1303 value. This must be a trivial immediate integer or floating-point 1304 constant. Undef or constant expressions are not valid. This is 1305 only valid on intrinsic declarations and cannot be applied to a 1306 call site or arbitrary function. 1307 1308``noundef`` 1309 This attribute applies to parameters and return values. If the value 1310 representation contains any undefined or poison bits, the behavior is 1311 undefined. Note that this does not refer to padding introduced by the 1312 type's storage representation. 1313 1314``alignstack(<n>)`` 1315 This indicates the alignment that should be considered by the backend when 1316 assigning this parameter to a stack slot during calling convention 1317 lowering. The enforcement of the specified alignment is target-dependent, 1318 as target-specific calling convention rules may override this value. This 1319 attribute serves the purpose of carrying language specific alignment 1320 information that is not mapped to base types in the backend (for example, 1321 over-alignment specification through language attributes). 1322 1323.. _gc: 1324 1325Garbage Collector Strategy Names 1326-------------------------------- 1327 1328Each function may specify a garbage collector strategy name, which is simply a 1329string: 1330 1331.. code-block:: llvm 1332 1333 define void @f() gc "name" { ... } 1334 1335The supported values of *name* includes those :ref:`built in to LLVM 1336<builtin-gc-strategies>` and any provided by loaded plugins. Specifying a GC 1337strategy will cause the compiler to alter its output in order to support the 1338named garbage collection algorithm. Note that LLVM itself does not contain a 1339garbage collector, this functionality is restricted to generating machine code 1340which can interoperate with a collector provided externally. 1341 1342.. _prefixdata: 1343 1344Prefix Data 1345----------- 1346 1347Prefix data is data associated with a function which the code 1348generator will emit immediately before the function's entrypoint. 1349The purpose of this feature is to allow frontends to associate 1350language-specific runtime metadata with specific functions and make it 1351available through the function pointer while still allowing the 1352function pointer to be called. 1353 1354To access the data for a given function, a program may bitcast the 1355function pointer to a pointer to the constant's type and dereference 1356index -1. This implies that the IR symbol points just past the end of 1357the prefix data. For instance, take the example of a function annotated 1358with a single ``i32``, 1359 1360.. code-block:: llvm 1361 1362 define void @f() prefix i32 123 { ... } 1363 1364The prefix data can be referenced as, 1365 1366.. code-block:: llvm 1367 1368 %0 = bitcast void* () @f to i32* 1369 %a = getelementptr inbounds i32, i32* %0, i32 -1 1370 %b = load i32, i32* %a 1371 1372Prefix data is laid out as if it were an initializer for a global variable 1373of the prefix data's type. The function will be placed such that the 1374beginning of the prefix data is aligned. This means that if the size 1375of the prefix data is not a multiple of the alignment size, the 1376function's entrypoint will not be aligned. If alignment of the 1377function's entrypoint is desired, padding must be added to the prefix 1378data. 1379 1380A function may have prefix data but no body. This has similar semantics 1381to the ``available_externally`` linkage in that the data may be used by the 1382optimizers but will not be emitted in the object file. 1383 1384.. _prologuedata: 1385 1386Prologue Data 1387------------- 1388 1389The ``prologue`` attribute allows arbitrary code (encoded as bytes) to 1390be inserted prior to the function body. This can be used for enabling 1391function hot-patching and instrumentation. 1392 1393To maintain the semantics of ordinary function calls, the prologue data must 1394have a particular format. Specifically, it must begin with a sequence of 1395bytes which decode to a sequence of machine instructions, valid for the 1396module's target, which transfer control to the point immediately succeeding 1397the prologue data, without performing any other visible action. This allows 1398the inliner and other passes to reason about the semantics of the function 1399definition without needing to reason about the prologue data. Obviously this 1400makes the format of the prologue data highly target dependent. 1401 1402A trivial example of valid prologue data for the x86 architecture is ``i8 144``, 1403which encodes the ``nop`` instruction: 1404 1405.. code-block:: text 1406 1407 define void @f() prologue i8 144 { ... } 1408 1409Generally prologue data can be formed by encoding a relative branch instruction 1410which skips the metadata, as in this example of valid prologue data for the 1411x86_64 architecture, where the first two bytes encode ``jmp .+10``: 1412 1413.. code-block:: text 1414 1415 %0 = type <{ i8, i8, i8* }> 1416 1417 define void @f() prologue %0 <{ i8 235, i8 8, i8* @md}> { ... } 1418 1419A function may have prologue data but no body. This has similar semantics 1420to the ``available_externally`` linkage in that the data may be used by the 1421optimizers but will not be emitted in the object file. 1422 1423.. _personalityfn: 1424 1425Personality Function 1426-------------------- 1427 1428The ``personality`` attribute permits functions to specify what function 1429to use for exception handling. 1430 1431.. _attrgrp: 1432 1433Attribute Groups 1434---------------- 1435 1436Attribute groups are groups of attributes that are referenced by objects within 1437the IR. They are important for keeping ``.ll`` files readable, because a lot of 1438functions will use the same set of attributes. In the degenerative case of a 1439``.ll`` file that corresponds to a single ``.c`` file, the single attribute 1440group will capture the important command line flags used to build that file. 1441 1442An attribute group is a module-level object. To use an attribute group, an 1443object references the attribute group's ID (e.g. ``#37``). An object may refer 1444to more than one attribute group. In that situation, the attributes from the 1445different groups are merged. 1446 1447Here is an example of attribute groups for a function that should always be 1448inlined, has a stack alignment of 4, and which shouldn't use SSE instructions: 1449 1450.. code-block:: llvm 1451 1452 ; Target-independent attributes: 1453 attributes #0 = { alwaysinline alignstack=4 } 1454 1455 ; Target-dependent attributes: 1456 attributes #1 = { "no-sse" } 1457 1458 ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse". 1459 define void @f() #0 #1 { ... } 1460 1461.. _fnattrs: 1462 1463Function Attributes 1464------------------- 1465 1466Function attributes are set to communicate additional information about 1467a function. Function attributes are considered to be part of the 1468function, not of the function type, so functions with different function 1469attributes can have the same function type. 1470 1471Function attributes are simple keywords that follow the type specified. 1472If multiple attributes are needed, they are space separated. For 1473example: 1474 1475.. code-block:: llvm 1476 1477 define void @f() noinline { ... } 1478 define void @f() alwaysinline { ... } 1479 define void @f() alwaysinline optsize { ... } 1480 define void @f() optsize { ... } 1481 1482``alignstack(<n>)`` 1483 This attribute indicates that, when emitting the prologue and 1484 epilogue, the backend should forcibly align the stack pointer. 1485 Specify the desired alignment, which must be a power of two, in 1486 parentheses. 1487``allocsize(<EltSizeParam>[, <NumEltsParam>])`` 1488 This attribute indicates that the annotated function will always return at 1489 least a given number of bytes (or null). Its arguments are zero-indexed 1490 parameter numbers; if one argument is provided, then it's assumed that at 1491 least ``CallSite.Args[EltSizeParam]`` bytes will be available at the 1492 returned pointer. If two are provided, then it's assumed that 1493 ``CallSite.Args[EltSizeParam] * CallSite.Args[NumEltsParam]`` bytes are 1494 available. The referenced parameters must be integer types. No assumptions 1495 are made about the contents of the returned block of memory. 1496``alwaysinline`` 1497 This attribute indicates that the inliner should attempt to inline 1498 this function into callers whenever possible, ignoring any active 1499 inlining size threshold for this caller. 1500``builtin`` 1501 This indicates that the callee function at a call site should be 1502 recognized as a built-in function, even though the function's declaration 1503 uses the ``nobuiltin`` attribute. This is only valid at call sites for 1504 direct calls to functions that are declared with the ``nobuiltin`` 1505 attribute. 1506``cold`` 1507 This attribute indicates that this function is rarely called. When 1508 computing edge weights, basic blocks post-dominated by a cold 1509 function call are also considered to be cold; and, thus, given low 1510 weight. 1511``convergent`` 1512 In some parallel execution models, there exist operations that cannot be 1513 made control-dependent on any additional values. We call such operations 1514 ``convergent``, and mark them with this attribute. 1515 1516 The ``convergent`` attribute may appear on functions or call/invoke 1517 instructions. When it appears on a function, it indicates that calls to 1518 this function should not be made control-dependent on additional values. 1519 For example, the intrinsic ``llvm.nvvm.barrier0`` is ``convergent``, so 1520 calls to this intrinsic cannot be made control-dependent on additional 1521 values. 1522 1523 When it appears on a call/invoke, the ``convergent`` attribute indicates 1524 that we should treat the call as though we're calling a convergent 1525 function. This is particularly useful on indirect calls; without this we 1526 may treat such calls as though the target is non-convergent. 1527 1528 The optimizer may remove the ``convergent`` attribute on functions when it 1529 can prove that the function does not execute any convergent operations. 1530 Similarly, the optimizer may remove ``convergent`` on calls/invokes when it 1531 can prove that the call/invoke cannot call a convergent function. 1532``"frame-pointer"`` 1533 This attribute tells the code generator whether the function 1534 should keep the frame pointer. The code generator may emit the frame pointer 1535 even if this attribute says the frame pointer can be eliminated. 1536 The allowed string values are: 1537 1538 * ``"none"`` (default) - the frame pointer can be eliminated. 1539 * ``"non-leaf"`` - the frame pointer should be kept if the function calls 1540 other functions. 1541 * ``"all"`` - the frame pointer should be kept. 1542``hot`` 1543 This attribute indicates that this function is a hot spot of the program 1544 execution. The function will be optimized more aggressively and will be 1545 placed into special subsection of the text section to improving locality. 1546 1547 When profile feedback is enabled, this attribute has the precedence over 1548 the profile information. By marking a function ``hot``, users can work 1549 around the cases where the training input does not have good coverage 1550 on all the hot functions. 1551``inaccessiblememonly`` 1552 This attribute indicates that the function may only access memory that 1553 is not accessible by the module being compiled. This is a weaker form 1554 of ``readnone``. If the function reads or writes other memory, the 1555 behavior is undefined. 1556``inaccessiblemem_or_argmemonly`` 1557 This attribute indicates that the function may only access memory that is 1558 either not accessible by the module being compiled, or is pointed to 1559 by its pointer arguments. This is a weaker form of ``argmemonly``. If the 1560 function reads or writes other memory, the behavior is undefined. 1561``inlinehint`` 1562 This attribute indicates that the source code contained a hint that 1563 inlining this function is desirable (such as the "inline" keyword in 1564 C/C++). It is just a hint; it imposes no requirements on the 1565 inliner. 1566``jumptable`` 1567 This attribute indicates that the function should be added to a 1568 jump-instruction table at code-generation time, and that all address-taken 1569 references to this function should be replaced with a reference to the 1570 appropriate jump-instruction-table function pointer. Note that this creates 1571 a new pointer for the original function, which means that code that depends 1572 on function-pointer identity can break. So, any function annotated with 1573 ``jumptable`` must also be ``unnamed_addr``. 1574``minsize`` 1575 This attribute suggests that optimization passes and code generator 1576 passes make choices that keep the code size of this function as small 1577 as possible and perform optimizations that may sacrifice runtime 1578 performance in order to minimize the size of the generated code. 1579``naked`` 1580 This attribute disables prologue / epilogue emission for the 1581 function. This can have very system-specific consequences. 1582``"no-inline-line-tables"`` 1583 When this attribute is set to true, the inliner discards source locations 1584 when inlining code and instead uses the source location of the call site. 1585 Breakpoints set on code that was inlined into the current function will 1586 not fire during the execution of the inlined call sites. If the debugger 1587 stops inside an inlined call site, it will appear to be stopped at the 1588 outermost inlined call site. 1589``no-jump-tables`` 1590 When this attribute is set to true, the jump tables and lookup tables that 1591 can be generated from a switch case lowering are disabled. 1592``nobuiltin`` 1593 This indicates that the callee function at a call site is not recognized as 1594 a built-in function. LLVM will retain the original call and not replace it 1595 with equivalent code based on the semantics of the built-in function, unless 1596 the call site uses the ``builtin`` attribute. This is valid at call sites 1597 and on function declarations and definitions. 1598``noduplicate`` 1599 This attribute indicates that calls to the function cannot be 1600 duplicated. A call to a ``noduplicate`` function may be moved 1601 within its parent function, but may not be duplicated within 1602 its parent function. 1603 1604 A function containing a ``noduplicate`` call may still 1605 be an inlining candidate, provided that the call is not 1606 duplicated by inlining. That implies that the function has 1607 internal linkage and only has one call site, so the original 1608 call is dead after inlining. 1609``nofree`` 1610 This function attribute indicates that the function does not, directly or 1611 transitively, call a memory-deallocation function (``free``, for example) 1612 on a memory allocation which existed before the call. 1613 1614 As a result, uncaptured pointers that are known to be dereferenceable 1615 prior to a call to a function with the ``nofree`` attribute are still 1616 known to be dereferenceable after the call. The capturing condition is 1617 necessary in environments where the function might communicate the 1618 pointer to another thread which then deallocates the memory. Alternatively, 1619 ``nosync`` would ensure such communication cannot happen and even captured 1620 pointers cannot be freed by the function. 1621 1622 A ``nofree`` function is explicitly allowed to free memory which it 1623 allocated or (if not ``nosync``) arrange for another thread to free 1624 memory on it's behalf. As a result, perhaps surprisingly, a ``nofree`` 1625 function can return a pointer to a previously deallocated memory object. 1626``noimplicitfloat`` 1627 This attributes disables implicit floating-point instructions. 1628``noinline`` 1629 This attribute indicates that the inliner should never inline this 1630 function in any situation. This attribute may not be used together 1631 with the ``alwaysinline`` attribute. 1632``nomerge`` 1633 This attribute indicates that calls to this function should never be merged 1634 during optimization. For example, it will prevent tail merging otherwise 1635 identical code sequences that raise an exception or terminate the program. 1636 Tail merging normally reduces the precision of source location information, 1637 making stack traces less useful for debugging. This attribute gives the 1638 user control over the tradeoff between code size and debug information 1639 precision. 1640``nonlazybind`` 1641 This attribute suppresses lazy symbol binding for the function. This 1642 may make calls to the function faster, at the cost of extra program 1643 startup time if the function is not called during program startup. 1644``noredzone`` 1645 This attribute indicates that the code generator should not use a 1646 red zone, even if the target-specific ABI normally permits it. 1647``indirect-tls-seg-refs`` 1648 This attribute indicates that the code generator should not use 1649 direct TLS access through segment registers, even if the 1650 target-specific ABI normally permits it. 1651``noreturn`` 1652 This function attribute indicates that the function never returns 1653 normally, hence through a return instruction. This produces undefined 1654 behavior at runtime if the function ever does dynamically return. Annotated 1655 functions may still raise an exception, i.a., ``nounwind`` is not implied. 1656``norecurse`` 1657 This function attribute indicates that the function does not call itself 1658 either directly or indirectly down any possible call path. This produces 1659 undefined behavior at runtime if the function ever does recurse. 1660``willreturn`` 1661 This function attribute indicates that a call of this function will 1662 either exhibit undefined behavior or comes back and continues execution 1663 at a point in the existing call stack that includes the current invocation. 1664 Annotated functions may still raise an exception, i.a., ``nounwind`` is not implied. 1665 If an invocation of an annotated function does not return control back 1666 to a point in the call stack, the behavior is undefined. 1667``nosync`` 1668 This function attribute indicates that the function does not communicate 1669 (synchronize) with another thread through memory or other well-defined means. 1670 Synchronization is considered possible in the presence of `atomic` accesses 1671 that enforce an order, thus not "unordered" and "monotonic", `volatile` accesses, 1672 as well as `convergent` function calls. Note that through `convergent` function calls 1673 non-memory communication, e.g., cross-lane operations, are possible and are also 1674 considered synchronization. However `convergent` does not contradict `nosync`. 1675 If an annotated function does ever synchronize with another thread, 1676 the behavior is undefined. 1677``nounwind`` 1678 This function attribute indicates that the function never raises an 1679 exception. If the function does raise an exception, its runtime 1680 behavior is undefined. However, functions marked nounwind may still 1681 trap or generate asynchronous exceptions. Exception handling schemes 1682 that are recognized by LLVM to handle asynchronous exceptions, such 1683 as SEH, will still provide their implementation defined semantics. 1684``null_pointer_is_valid`` 1685 If ``null_pointer_is_valid`` is set, then the ``null`` address 1686 in address-space 0 is considered to be a valid address for memory loads and 1687 stores. Any analysis or optimization should not treat dereferencing a 1688 pointer to ``null`` as undefined behavior in this function. 1689 Note: Comparing address of a global variable to ``null`` may still 1690 evaluate to false because of a limitation in querying this attribute inside 1691 constant expressions. 1692``optforfuzzing`` 1693 This attribute indicates that this function should be optimized 1694 for maximum fuzzing signal. 1695``optnone`` 1696 This function attribute indicates that most optimization passes will skip 1697 this function, with the exception of interprocedural optimization passes. 1698 Code generation defaults to the "fast" instruction selector. 1699 This attribute cannot be used together with the ``alwaysinline`` 1700 attribute; this attribute is also incompatible 1701 with the ``minsize`` attribute and the ``optsize`` attribute. 1702 1703 This attribute requires the ``noinline`` attribute to be specified on 1704 the function as well, so the function is never inlined into any caller. 1705 Only functions with the ``alwaysinline`` attribute are valid 1706 candidates for inlining into the body of this function. 1707``optsize`` 1708 This attribute suggests that optimization passes and code generator 1709 passes make choices that keep the code size of this function low, 1710 and otherwise do optimizations specifically to reduce code size as 1711 long as they do not significantly impact runtime performance. 1712``"patchable-function"`` 1713 This attribute tells the code generator that the code 1714 generated for this function needs to follow certain conventions that 1715 make it possible for a runtime function to patch over it later. 1716 The exact effect of this attribute depends on its string value, 1717 for which there currently is one legal possibility: 1718 1719 * ``"prologue-short-redirect"`` - This style of patchable 1720 function is intended to support patching a function prologue to 1721 redirect control away from the function in a thread safe 1722 manner. It guarantees that the first instruction of the 1723 function will be large enough to accommodate a short jump 1724 instruction, and will be sufficiently aligned to allow being 1725 fully changed via an atomic compare-and-swap instruction. 1726 While the first requirement can be satisfied by inserting large 1727 enough NOP, LLVM can and will try to re-purpose an existing 1728 instruction (i.e. one that would have to be emitted anyway) as 1729 the patchable instruction larger than a short jump. 1730 1731 ``"prologue-short-redirect"`` is currently only supported on 1732 x86-64. 1733 1734 This attribute by itself does not imply restrictions on 1735 inter-procedural optimizations. All of the semantic effects the 1736 patching may have to be separately conveyed via the linkage type. 1737``"probe-stack"`` 1738 This attribute indicates that the function will trigger a guard region 1739 in the end of the stack. It ensures that accesses to the stack must be 1740 no further apart than the size of the guard region to a previous 1741 access of the stack. It takes one required string value, the name of 1742 the stack probing function that will be called. 1743 1744 If a function that has a ``"probe-stack"`` attribute is inlined into 1745 a function with another ``"probe-stack"`` attribute, the resulting 1746 function has the ``"probe-stack"`` attribute of the caller. If a 1747 function that has a ``"probe-stack"`` attribute is inlined into a 1748 function that has no ``"probe-stack"`` attribute at all, the resulting 1749 function has the ``"probe-stack"`` attribute of the callee. 1750``readnone`` 1751 On a function, this attribute indicates that the function computes its 1752 result (or decides to unwind an exception) based strictly on its arguments, 1753 without dereferencing any pointer arguments or otherwise accessing 1754 any mutable state (e.g. memory, control registers, etc) visible to 1755 caller functions. It does not write through any pointer arguments 1756 (including ``byval`` arguments) and never changes any state visible 1757 to callers. This means while it cannot unwind exceptions by calling 1758 the ``C++`` exception throwing methods (since they write to memory), there may 1759 be non-``C++`` mechanisms that throw exceptions without writing to LLVM 1760 visible memory. 1761 1762 On an argument, this attribute indicates that the function does not 1763 dereference that pointer argument, even though it may read or write the 1764 memory that the pointer points to if accessed through other pointers. 1765 1766 If a readnone function reads or writes memory visible to the program, or 1767 has other side-effects, the behavior is undefined. If a function reads from 1768 or writes to a readnone pointer argument, the behavior is undefined. 1769``readonly`` 1770 On a function, this attribute indicates that the function does not write 1771 through any pointer arguments (including ``byval`` arguments) or otherwise 1772 modify any state (e.g. memory, control registers, etc) visible to 1773 caller functions. It may dereference pointer arguments and read 1774 state that may be set in the caller. A readonly function always 1775 returns the same value (or unwinds an exception identically) when 1776 called with the same set of arguments and global state. This means while it 1777 cannot unwind exceptions by calling the ``C++`` exception throwing methods 1778 (since they write to memory), there may be non-``C++`` mechanisms that throw 1779 exceptions without writing to LLVM visible memory. 1780 1781 On an argument, this attribute indicates that the function does not write 1782 through this pointer argument, even though it may write to the memory that 1783 the pointer points to. 1784 1785 If a readonly function writes memory visible to the program, or 1786 has other side-effects, the behavior is undefined. If a function writes to 1787 a readonly pointer argument, the behavior is undefined. 1788``"stack-probe-size"`` 1789 This attribute controls the behavior of stack probes: either 1790 the ``"probe-stack"`` attribute, or ABI-required stack probes, if any. 1791 It defines the size of the guard region. It ensures that if the function 1792 may use more stack space than the size of the guard region, stack probing 1793 sequence will be emitted. It takes one required integer value, which 1794 is 4096 by default. 1795 1796 If a function that has a ``"stack-probe-size"`` attribute is inlined into 1797 a function with another ``"stack-probe-size"`` attribute, the resulting 1798 function has the ``"stack-probe-size"`` attribute that has the lower 1799 numeric value. If a function that has a ``"stack-probe-size"`` attribute is 1800 inlined into a function that has no ``"stack-probe-size"`` attribute 1801 at all, the resulting function has the ``"stack-probe-size"`` attribute 1802 of the callee. 1803``"no-stack-arg-probe"`` 1804 This attribute disables ABI-required stack probes, if any. 1805``writeonly`` 1806 On a function, this attribute indicates that the function may write to but 1807 does not read from memory. 1808 1809 On an argument, this attribute indicates that the function may write to but 1810 does not read through this pointer argument (even though it may read from 1811 the memory that the pointer points to). 1812 1813 If a writeonly function reads memory visible to the program, or 1814 has other side-effects, the behavior is undefined. If a function reads 1815 from a writeonly pointer argument, the behavior is undefined. 1816``argmemonly`` 1817 This attribute indicates that the only memory accesses inside function are 1818 loads and stores from objects pointed to by its pointer-typed arguments, 1819 with arbitrary offsets. Or in other words, all memory operations in the 1820 function can refer to memory only using pointers based on its function 1821 arguments. 1822 1823 Note that ``argmemonly`` can be used together with ``readonly`` attribute 1824 in order to specify that function reads only from its arguments. 1825 1826 If an argmemonly function reads or writes memory other than the pointer 1827 arguments, or has other side-effects, the behavior is undefined. 1828``returns_twice`` 1829 This attribute indicates that this function can return twice. The C 1830 ``setjmp`` is an example of such a function. The compiler disables 1831 some optimizations (like tail calls) in the caller of these 1832 functions. 1833``safestack`` 1834 This attribute indicates that 1835 `SafeStack <https://clang.llvm.org/docs/SafeStack.html>`_ 1836 protection is enabled for this function. 1837 1838 If a function that has a ``safestack`` attribute is inlined into a 1839 function that doesn't have a ``safestack`` attribute or which has an 1840 ``ssp``, ``sspstrong`` or ``sspreq`` attribute, then the resulting 1841 function will have a ``safestack`` attribute. 1842``sanitize_address`` 1843 This attribute indicates that AddressSanitizer checks 1844 (dynamic address safety analysis) are enabled for this function. 1845``sanitize_memory`` 1846 This attribute indicates that MemorySanitizer checks (dynamic detection 1847 of accesses to uninitialized memory) are enabled for this function. 1848``sanitize_thread`` 1849 This attribute indicates that ThreadSanitizer checks 1850 (dynamic thread safety analysis) are enabled for this function. 1851``sanitize_hwaddress`` 1852 This attribute indicates that HWAddressSanitizer checks 1853 (dynamic address safety analysis based on tagged pointers) are enabled for 1854 this function. 1855``sanitize_memtag`` 1856 This attribute indicates that MemTagSanitizer checks 1857 (dynamic address safety analysis based on Armv8 MTE) are enabled for 1858 this function. 1859``speculative_load_hardening`` 1860 This attribute indicates that 1861 `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_ 1862 should be enabled for the function body. 1863 1864 Speculative Load Hardening is a best-effort mitigation against 1865 information leak attacks that make use of control flow 1866 miss-speculation - specifically miss-speculation of whether a branch 1867 is taken or not. Typically vulnerabilities enabling such attacks are 1868 classified as "Spectre variant #1". Notably, this does not attempt to 1869 mitigate against miss-speculation of branch target, classified as 1870 "Spectre variant #2" vulnerabilities. 1871 1872 When inlining, the attribute is sticky. Inlining a function that carries 1873 this attribute will cause the caller to gain the attribute. This is intended 1874 to provide a maximally conservative model where the code in a function 1875 annotated with this attribute will always (even after inlining) end up 1876 hardened. 1877``speculatable`` 1878 This function attribute indicates that the function does not have any 1879 effects besides calculating its result and does not have undefined behavior. 1880 Note that ``speculatable`` is not enough to conclude that along any 1881 particular execution path the number of calls to this function will not be 1882 externally observable. This attribute is only valid on functions 1883 and declarations, not on individual call sites. If a function is 1884 incorrectly marked as speculatable and really does exhibit 1885 undefined behavior, the undefined behavior may be observed even 1886 if the call site is dead code. 1887 1888``ssp`` 1889 This attribute indicates that the function should emit a stack 1890 smashing protector. It is in the form of a "canary" --- a random value 1891 placed on the stack before the local variables that's checked upon 1892 return from the function to see if it has been overwritten. A 1893 heuristic is used to determine if a function needs stack protectors 1894 or not. The heuristic used will enable protectors for functions with: 1895 1896 - Character arrays larger than ``ssp-buffer-size`` (default 8). 1897 - Aggregates containing character arrays larger than ``ssp-buffer-size``. 1898 - Calls to alloca() with variable sizes or constant sizes greater than 1899 ``ssp-buffer-size``. 1900 1901 Variables that are identified as requiring a protector will be arranged 1902 on the stack such that they are adjacent to the stack protector guard. 1903 1904 A function with the ``ssp`` attribute but without the ``alwaysinline`` 1905 attribute cannot be inlined into a function without a 1906 ``ssp/sspreq/sspstrong`` attribute. If inlined, the caller will get the 1907 ``ssp`` attribute. 1908``sspstrong`` 1909 This attribute indicates that the function should emit a stack smashing 1910 protector. This attribute causes a strong heuristic to be used when 1911 determining if a function needs stack protectors. The strong heuristic 1912 will enable protectors for functions with: 1913 1914 - Arrays of any size and type 1915 - Aggregates containing an array of any size and type. 1916 - Calls to alloca(). 1917 - Local variables that have had their address taken. 1918 1919 Variables that are identified as requiring a protector will be arranged 1920 on the stack such that they are adjacent to the stack protector guard. 1921 The specific layout rules are: 1922 1923 #. Large arrays and structures containing large arrays 1924 (``>= ssp-buffer-size``) are closest to the stack protector. 1925 #. Small arrays and structures containing small arrays 1926 (``< ssp-buffer-size``) are 2nd closest to the protector. 1927 #. Variables that have had their address taken are 3rd closest to the 1928 protector. 1929 1930 This overrides the ``ssp`` function attribute. 1931 1932 A function with the ``sspstrong`` attribute but without the 1933 ``alwaysinline`` attribute cannot be inlined into a function without a 1934 ``ssp/sspstrong/sspreq`` attribute. If inlined, the caller will get the 1935 ``sspstrong`` attribute unless the ``sspreq`` attribute exists. 1936``sspreq`` 1937 This attribute indicates that the function should *always* emit a stack 1938 smashing protector. This overrides the ``ssp`` and ``sspstrong`` function 1939 attributes. 1940 1941 Variables that are identified as requiring a protector will be arranged 1942 on the stack such that they are adjacent to the stack protector guard. 1943 The specific layout rules are: 1944 1945 #. Large arrays and structures containing large arrays 1946 (``>= ssp-buffer-size``) are closest to the stack protector. 1947 #. Small arrays and structures containing small arrays 1948 (``< ssp-buffer-size``) are 2nd closest to the protector. 1949 #. Variables that have had their address taken are 3rd closest to the 1950 protector. 1951 1952 A function with the ``sspreq`` attribute but without the ``alwaysinline`` 1953 attribute cannot be inlined into a function without a 1954 ``ssp/sspstrong/sspreq`` attribute. If inlined, the caller will get the 1955 ``sspreq`` attribute. 1956 1957``strictfp`` 1958 This attribute indicates that the function was called from a scope that 1959 requires strict floating-point semantics. LLVM will not attempt any 1960 optimizations that require assumptions about the floating-point rounding 1961 mode or that might alter the state of floating-point status flags that 1962 might otherwise be set or cleared by calling this function. LLVM will 1963 not introduce any new floating-point instructions that may trap. 1964 1965``"denormal-fp-math"`` 1966 This indicates the denormal (subnormal) handling that may be 1967 assumed for the default floating-point environment. This is a 1968 comma separated pair. The elements may be one of ``"ieee"``, 1969 ``"preserve-sign"``, or ``"positive-zero"``. The first entry 1970 indicates the flushing mode for the result of floating point 1971 operations. The second indicates the handling of denormal inputs 1972 to floating point instructions. For compatibility with older 1973 bitcode, if the second value is omitted, both input and output 1974 modes will assume the same mode. 1975 1976 If this is attribute is not specified, the default is 1977 ``"ieee,ieee"``. 1978 1979 If the output mode is ``"preserve-sign"``, or ``"positive-zero"``, 1980 denormal outputs may be flushed to zero by standard floating-point 1981 operations. It is not mandated that flushing to zero occurs, but if 1982 a denormal output is flushed to zero, it must respect the sign 1983 mode. Not all targets support all modes. While this indicates the 1984 expected floating point mode the function will be executed with, 1985 this does not make any attempt to ensure the mode is 1986 consistent. User or platform code is expected to set the floating 1987 point mode appropriately before function entry. 1988 1989 If the input mode is ``"preserve-sign"``, or ``"positive-zero"``, a 1990 floating-point operation must treat any input denormal value as 1991 zero. In some situations, if an instruction does not respect this 1992 mode, the input may need to be converted to 0 as if by 1993 ``@llvm.canonicalize`` during lowering for correctness. 1994 1995``"denormal-fp-math-f32"`` 1996 Same as ``"denormal-fp-math"``, but only controls the behavior of 1997 the 32-bit float type (or vectors of 32-bit floats). If both are 1998 are present, this overrides ``"denormal-fp-math"``. Not all targets 1999 support separately setting the denormal mode per type, and no 2000 attempt is made to diagnose unsupported uses. Currently this 2001 attribute is respected by the AMDGPU and NVPTX backends. 2002 2003``"thunk"`` 2004 This attribute indicates that the function will delegate to some other 2005 function with a tail call. The prototype of a thunk should not be used for 2006 optimization purposes. The caller is expected to cast the thunk prototype to 2007 match the thunk target prototype. 2008``uwtable`` 2009 This attribute indicates that the ABI being targeted requires that 2010 an unwind table entry be produced for this function even if we can 2011 show that no exceptions passes by it. This is normally the case for 2012 the ELF x86-64 abi, but it can be disabled for some compilation 2013 units. 2014``nocf_check`` 2015 This attribute indicates that no control-flow check will be performed on 2016 the attributed entity. It disables -fcf-protection=<> for a specific 2017 entity to fine grain the HW control flow protection mechanism. The flag 2018 is target independent and currently appertains to a function or function 2019 pointer. 2020``shadowcallstack`` 2021 This attribute indicates that the ShadowCallStack checks are enabled for 2022 the function. The instrumentation checks that the return address for the 2023 function has not changed between the function prolog and epilog. It is 2024 currently x86_64-specific. 2025``mustprogress`` 2026 This attribute indicates that the function is required to return, unwind, 2027 or interact with the environment in an observable way e.g. via a volatile 2028 memory access, I/O, or other synchronization. The ``mustprogress`` 2029 attribute is intended to model the requirements of the first section of 2030 [intro.progress] of the C++ Standard. As a consequence, a loop in a 2031 function with the `mustprogress` attribute can be assumed to terminate if 2032 it does not interact with the environment in an observable way, and 2033 terminating loops without side-effects can be removed. If a `mustprogress` 2034 function does not satisfy this contract, the behavior is undefined. This 2035 attribute does not apply transitively to callees, but does apply to call 2036 sites within the function. Note that `willreturn` implies `mustprogress`. 2037``vscale_range(<min>[, <max>])`` 2038 This attribute indicates the minimum and maximum vscale value for the given 2039 function. A value of 0 means unbounded. If the optional max value is omitted 2040 then max is set to the value of min. If the attribute is not present, no 2041 assumptions are made about the range of vscale. 2042 2043Call Site Attributes 2044---------------------- 2045 2046In addition to function attributes the following call site only 2047attributes are supported: 2048 2049``vector-function-abi-variant`` 2050 This attribute can be attached to a :ref:`call <i_call>` to list 2051 the vector functions associated to the function. Notice that the 2052 attribute cannot be attached to a :ref:`invoke <i_invoke>` or a 2053 :ref:`callbr <i_callbr>` instruction. The attribute consists of a 2054 comma separated list of mangled names. The order of the list does 2055 not imply preference (it is logically a set). The compiler is free 2056 to pick any listed vector function of its choosing. 2057 2058 The syntax for the mangled names is as follows::: 2059 2060 _ZGV<isa><mask><vlen><parameters>_<scalar_name>[(<vector_redirection>)] 2061 2062 When present, the attribute informs the compiler that the function 2063 ``<scalar_name>`` has a corresponding vector variant that can be 2064 used to perform the concurrent invocation of ``<scalar_name>`` on 2065 vectors. The shape of the vector function is described by the 2066 tokens between the prefix ``_ZGV`` and the ``<scalar_name>`` 2067 token. The standard name of the vector function is 2068 ``_ZGV<isa><mask><vlen><parameters>_<scalar_name>``. When present, 2069 the optional token ``(<vector_redirection>)`` informs the compiler 2070 that a custom name is provided in addition to the standard one 2071 (custom names can be provided for example via the use of ``declare 2072 variant`` in OpenMP 5.0). The declaration of the variant must be 2073 present in the IR Module. The signature of the vector variant is 2074 determined by the rules of the Vector Function ABI (VFABI) 2075 specifications of the target. For Arm and X86, the VFABI can be 2076 found at https://github.com/ARM-software/abi-aa and 2077 https://software.intel.com/en-us/articles/vector-simd-function-abi, 2078 respectively. 2079 2080 For X86 and Arm targets, the values of the tokens in the standard 2081 name are those that are defined in the VFABI. LLVM has an internal 2082 ``<isa>`` token that can be used to create scalar-to-vector 2083 mappings for functions that are not directly associated to any of 2084 the target ISAs (for example, some of the mappings stored in the 2085 TargetLibraryInfo). Valid values for the ``<isa>`` token are::: 2086 2087 <isa>:= b | c | d | e -> X86 SSE, AVX, AVX2, AVX512 2088 | n | s -> Armv8 Advanced SIMD, SVE 2089 | __LLVM__ -> Internal LLVM Vector ISA 2090 2091 For all targets currently supported (x86, Arm and Internal LLVM), 2092 the remaining tokens can have the following values::: 2093 2094 <mask>:= M | N -> mask | no mask 2095 2096 <vlen>:= number -> number of lanes 2097 | x -> VLA (Vector Length Agnostic) 2098 2099 <parameters>:= v -> vector 2100 | l | l <number> -> linear 2101 | R | R <number> -> linear with ref modifier 2102 | L | L <number> -> linear with val modifier 2103 | U | U <number> -> linear with uval modifier 2104 | ls <pos> -> runtime linear 2105 | Rs <pos> -> runtime linear with ref modifier 2106 | Ls <pos> -> runtime linear with val modifier 2107 | Us <pos> -> runtime linear with uval modifier 2108 | u -> uniform 2109 2110 <scalar_name>:= name of the scalar function 2111 2112 <vector_redirection>:= optional, custom name of the vector function 2113 2114``preallocated(<ty>)`` 2115 This attribute is required on calls to ``llvm.call.preallocated.arg`` 2116 and cannot be used on any other call. See 2117 :ref:`llvm.call.preallocated.arg<int_call_preallocated_arg>` for more 2118 details. 2119 2120.. _glattrs: 2121 2122Global Attributes 2123----------------- 2124 2125Attributes may be set to communicate additional information about a global variable. 2126Unlike :ref:`function attributes <fnattrs>`, attributes on a global variable 2127are grouped into a single :ref:`attribute group <attrgrp>`. 2128 2129.. _opbundles: 2130 2131Operand Bundles 2132--------------- 2133 2134Operand bundles are tagged sets of SSA values that can be associated 2135with certain LLVM instructions (currently only ``call`` s and 2136``invoke`` s). In a way they are like metadata, but dropping them is 2137incorrect and will change program semantics. 2138 2139Syntax:: 2140 2141 operand bundle set ::= '[' operand bundle (, operand bundle )* ']' 2142 operand bundle ::= tag '(' [ bundle operand ] (, bundle operand )* ')' 2143 bundle operand ::= SSA value 2144 tag ::= string constant 2145 2146Operand bundles are **not** part of a function's signature, and a 2147given function may be called from multiple places with different kinds 2148of operand bundles. This reflects the fact that the operand bundles 2149are conceptually a part of the ``call`` (or ``invoke``), not the 2150callee being dispatched to. 2151 2152Operand bundles are a generic mechanism intended to support 2153runtime-introspection-like functionality for managed languages. While 2154the exact semantics of an operand bundle depend on the bundle tag, 2155there are certain limitations to how much the presence of an operand 2156bundle can influence the semantics of a program. These restrictions 2157are described as the semantics of an "unknown" operand bundle. As 2158long as the behavior of an operand bundle is describable within these 2159restrictions, LLVM does not need to have special knowledge of the 2160operand bundle to not miscompile programs containing it. 2161 2162- The bundle operands for an unknown operand bundle escape in unknown 2163 ways before control is transferred to the callee or invokee. 2164- Calls and invokes with operand bundles have unknown read / write 2165 effect on the heap on entry and exit (even if the call target is 2166 ``readnone`` or ``readonly``), unless they're overridden with 2167 callsite specific attributes. 2168- An operand bundle at a call site cannot change the implementation 2169 of the called function. Inter-procedural optimizations work as 2170 usual as long as they take into account the first two properties. 2171 2172More specific types of operand bundles are described below. 2173 2174.. _deopt_opbundles: 2175 2176Deoptimization Operand Bundles 2177^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2178 2179Deoptimization operand bundles are characterized by the ``"deopt"`` 2180operand bundle tag. These operand bundles represent an alternate 2181"safe" continuation for the call site they're attached to, and can be 2182used by a suitable runtime to deoptimize the compiled frame at the 2183specified call site. There can be at most one ``"deopt"`` operand 2184bundle attached to a call site. Exact details of deoptimization is 2185out of scope for the language reference, but it usually involves 2186rewriting a compiled frame into a set of interpreted frames. 2187 2188From the compiler's perspective, deoptimization operand bundles make 2189the call sites they're attached to at least ``readonly``. They read 2190through all of their pointer typed operands (even if they're not 2191otherwise escaped) and the entire visible heap. Deoptimization 2192operand bundles do not capture their operands except during 2193deoptimization, in which case control will not be returned to the 2194compiled frame. 2195 2196The inliner knows how to inline through calls that have deoptimization 2197operand bundles. Just like inlining through a normal call site 2198involves composing the normal and exceptional continuations, inlining 2199through a call site with a deoptimization operand bundle needs to 2200appropriately compose the "safe" deoptimization continuation. The 2201inliner does this by prepending the parent's deoptimization 2202continuation to every deoptimization continuation in the inlined body. 2203E.g. inlining ``@f`` into ``@g`` in the following example 2204 2205.. code-block:: llvm 2206 2207 define void @f() { 2208 call void @x() ;; no deopt state 2209 call void @y() [ "deopt"(i32 10) ] 2210 call void @y() [ "deopt"(i32 10), "unknown"(i8* null) ] 2211 ret void 2212 } 2213 2214 define void @g() { 2215 call void @f() [ "deopt"(i32 20) ] 2216 ret void 2217 } 2218 2219will result in 2220 2221.. code-block:: llvm 2222 2223 define void @g() { 2224 call void @x() ;; still no deopt state 2225 call void @y() [ "deopt"(i32 20, i32 10) ] 2226 call void @y() [ "deopt"(i32 20, i32 10), "unknown"(i8* null) ] 2227 ret void 2228 } 2229 2230It is the frontend's responsibility to structure or encode the 2231deoptimization state in a way that syntactically prepending the 2232caller's deoptimization state to the callee's deoptimization state is 2233semantically equivalent to composing the caller's deoptimization 2234continuation after the callee's deoptimization continuation. 2235 2236.. _ob_funclet: 2237 2238Funclet Operand Bundles 2239^^^^^^^^^^^^^^^^^^^^^^^ 2240 2241Funclet operand bundles are characterized by the ``"funclet"`` 2242operand bundle tag. These operand bundles indicate that a call site 2243is within a particular funclet. There can be at most one 2244``"funclet"`` operand bundle attached to a call site and it must have 2245exactly one bundle operand. 2246 2247If any funclet EH pads have been "entered" but not "exited" (per the 2248`description in the EH doc\ <ExceptionHandling.html#wineh-constraints>`_), 2249it is undefined behavior to execute a ``call`` or ``invoke`` which: 2250 2251* does not have a ``"funclet"`` bundle and is not a ``call`` to a nounwind 2252 intrinsic, or 2253* has a ``"funclet"`` bundle whose operand is not the most-recently-entered 2254 not-yet-exited funclet EH pad. 2255 2256Similarly, if no funclet EH pads have been entered-but-not-yet-exited, 2257executing a ``call`` or ``invoke`` with a ``"funclet"`` bundle is undefined behavior. 2258 2259GC Transition Operand Bundles 2260^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2261 2262GC transition operand bundles are characterized by the 2263``"gc-transition"`` operand bundle tag. These operand bundles mark a 2264call as a transition between a function with one GC strategy to a 2265function with a different GC strategy. If coordinating the transition 2266between GC strategies requires additional code generation at the call 2267site, these bundles may contain any values that are needed by the 2268generated code. For more details, see :ref:`GC Transitions 2269<gc_transition_args>`. 2270 2271The bundle contain an arbitrary list of Values which need to be passed 2272to GC transition code. They will be lowered and passed as operands to 2273the appropriate GC_TRANSITION nodes in the selection DAG. It is assumed 2274that these arguments must be available before and after (but not 2275necessarily during) the execution of the callee. 2276 2277.. _assume_opbundles: 2278 2279Assume Operand Bundles 2280^^^^^^^^^^^^^^^^^^^^^^ 2281 2282Operand bundles on an :ref:`llvm.assume <int_assume>` allows representing 2283assumptions that a :ref:`parameter attribute <paramattrs>` or a 2284:ref:`function attribute <fnattrs>` holds for a certain value at a certain 2285location. Operand bundles enable assumptions that are either hard or impossible 2286to represent as a boolean argument of an :ref:`llvm.assume <int_assume>`. 2287 2288An assume operand bundle has the form: 2289 2290:: 2291 2292 "<tag>"([ <holds for value> [, <attribute argument>] ]) 2293 2294* The tag of the operand bundle is usually the name of attribute that can be 2295 assumed to hold. It can also be `ignore`, this tag doesn't contain any 2296 information and should be ignored. 2297* The first argument if present is the value for which the attribute hold. 2298* The second argument if present is an argument of the attribute. 2299 2300If there are no arguments the attribute is a property of the call location. 2301 2302If the represented attribute expects a constant argument, the argument provided 2303to the operand bundle should be a constant as well. 2304 2305For example: 2306 2307.. code-block:: llvm 2308 2309 call void @llvm.assume(i1 true) ["align"(i32* %val, i32 8)] 2310 2311allows the optimizer to assume that at location of call to 2312:ref:`llvm.assume <int_assume>` ``%val`` has an alignment of at least 8. 2313 2314.. code-block:: llvm 2315 2316 call void @llvm.assume(i1 %cond) ["cold"(), "nonnull"(i64* %val)] 2317 2318allows the optimizer to assume that the :ref:`llvm.assume <int_assume>` 2319call location is cold and that ``%val`` may not be null. 2320 2321Just like for the argument of :ref:`llvm.assume <int_assume>`, if any of the 2322provided guarantees are violated at runtime the behavior is undefined. 2323 2324Even if the assumed property can be encoded as a boolean value, like 2325``nonnull``, using operand bundles to express the property can still have 2326benefits: 2327 2328* Attributes that can be expressed via operand bundles are directly the 2329 property that the optimizer uses and cares about. Encoding attributes as 2330 operand bundles removes the need for an instruction sequence that represents 2331 the property (e.g., `icmp ne i32* %p, null` for `nonnull`) and for the 2332 optimizer to deduce the property from that instruction sequence. 2333* Expressing the property using operand bundles makes it easy to identify the 2334 use of the value as a use in an :ref:`llvm.assume <int_assume>`. This then 2335 simplifies and improves heuristics, e.g., for use "use-sensitive" 2336 optimizations. 2337 2338.. _ob_preallocated: 2339 2340Preallocated Operand Bundles 2341^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2342 2343Preallocated operand bundles are characterized by the ``"preallocated"`` 2344operand bundle tag. These operand bundles allow separation of the allocation 2345of the call argument memory from the call site. This is necessary to pass 2346non-trivially copyable objects by value in a way that is compatible with MSVC 2347on some targets. There can be at most one ``"preallocated"`` operand bundle 2348attached to a call site and it must have exactly one bundle operand, which is 2349a token generated by ``@llvm.call.preallocated.setup``. A call with this 2350operand bundle should not adjust the stack before entering the function, as 2351that will have been done by one of the ``@llvm.call.preallocated.*`` intrinsics. 2352 2353.. code-block:: llvm 2354 2355 %foo = type { i64, i32 } 2356 2357 ... 2358 2359 %t = call token @llvm.call.preallocated.setup(i32 1) 2360 %a = call i8* @llvm.call.preallocated.arg(token %t, i32 0) preallocated(%foo) 2361 %b = bitcast i8* %a to %foo* 2362 ; initialize %b 2363 call void @bar(i32 42, %foo* preallocated(%foo) %b) ["preallocated"(token %t)] 2364 2365.. _ob_gc_live: 2366 2367GC Live Operand Bundles 2368^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2369 2370A "gc-live" operand bundle is only valid on a :ref:`gc.statepoint <gc_statepoint>` 2371intrinsic. The operand bundle must contain every pointer to a garbage collected 2372object which potentially needs to be updated by the garbage collector. 2373 2374When lowered, any relocated value will be recorded in the corresponding 2375:ref:`stackmap entry <statepoint-stackmap-format>`. See the intrinsic description 2376for further details. 2377 2378ObjC ARC Attached Call Operand Bundles 2379^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2380 2381A ``"clang.arc.attachedcall`` operand bundle on a call indicates the call is 2382implicitly followed by a marker instruction and a call to an ObjC runtime 2383function that uses the result of the call. If the argument passed to the operand 2384bundle is 0, ``@objc_retainAutoreleasedReturnValue`` is called. If 1 is passed, 2385``@objc_unsafeClaimAutoreleasedReturnValue`` is called. A call with this bundle 2386implicitly uses its return value. 2387 2388The operand bundle is needed to ensure the call is immediately followed by the 2389marker instruction or the ObjC runtime call in the final output. 2390 2391.. _moduleasm: 2392 2393Module-Level Inline Assembly 2394---------------------------- 2395 2396Modules may contain "module-level inline asm" blocks, which corresponds 2397to the GCC "file scope inline asm" blocks. These blocks are internally 2398concatenated by LLVM and treated as a single unit, but may be separated 2399in the ``.ll`` file if desired. The syntax is very simple: 2400 2401.. code-block:: llvm 2402 2403 module asm "inline asm code goes here" 2404 module asm "more can go here" 2405 2406The strings can contain any character by escaping non-printable 2407characters. The escape sequence used is simply "\\xx" where "xx" is the 2408two digit hex code for the number. 2409 2410Note that the assembly string *must* be parseable by LLVM's integrated assembler 2411(unless it is disabled), even when emitting a ``.s`` file. 2412 2413.. _langref_datalayout: 2414 2415Data Layout 2416----------- 2417 2418A module may specify a target specific data layout string that specifies 2419how data is to be laid out in memory. The syntax for the data layout is 2420simply: 2421 2422.. code-block:: llvm 2423 2424 target datalayout = "layout specification" 2425 2426The *layout specification* consists of a list of specifications 2427separated by the minus sign character ('-'). Each specification starts 2428with a letter and may include other information after the letter to 2429define some aspect of the data layout. The specifications accepted are 2430as follows: 2431 2432``E`` 2433 Specifies that the target lays out data in big-endian form. That is, 2434 the bits with the most significance have the lowest address 2435 location. 2436``e`` 2437 Specifies that the target lays out data in little-endian form. That 2438 is, the bits with the least significance have the lowest address 2439 location. 2440``S<size>`` 2441 Specifies the natural alignment of the stack in bits. Alignment 2442 promotion of stack variables is limited to the natural stack 2443 alignment to avoid dynamic stack realignment. The stack alignment 2444 must be a multiple of 8-bits. If omitted, the natural stack 2445 alignment defaults to "unspecified", which does not prevent any 2446 alignment promotions. 2447``P<address space>`` 2448 Specifies the address space that corresponds to program memory. 2449 Harvard architectures can use this to specify what space LLVM 2450 should place things such as functions into. If omitted, the 2451 program memory space defaults to the default address space of 0, 2452 which corresponds to a Von Neumann architecture that has code 2453 and data in the same space. 2454``G<address space>`` 2455 Specifies the address space to be used by default when creating global 2456 variables. If omitted, the globals address space defaults to the default 2457 address space 0. 2458 Note: variable declarations without an address space are always created in 2459 address space 0, this property only affects the default value to be used 2460 when creating globals without additional contextual information (e.g. in 2461 LLVM passes). 2462``A<address space>`` 2463 Specifies the address space of objects created by '``alloca``'. 2464 Defaults to the default address space of 0. 2465``p[n]:<size>:<abi>:<pref>:<idx>`` 2466 This specifies the *size* of a pointer and its ``<abi>`` and 2467 ``<pref>``\erred alignments for address space ``n``. The fourth parameter 2468 ``<idx>`` is a size of index that used for address calculation. If not 2469 specified, the default index size is equal to the pointer size. All sizes 2470 are in bits. The address space, ``n``, is optional, and if not specified, 2471 denotes the default address space 0. The value of ``n`` must be 2472 in the range [1,2^23). 2473``i<size>:<abi>:<pref>`` 2474 This specifies the alignment for an integer type of a given bit 2475 ``<size>``. The value of ``<size>`` must be in the range [1,2^23). 2476``v<size>:<abi>:<pref>`` 2477 This specifies the alignment for a vector type of a given bit 2478 ``<size>``. 2479``f<size>:<abi>:<pref>`` 2480 This specifies the alignment for a floating-point type of a given bit 2481 ``<size>``. Only values of ``<size>`` that are supported by the target 2482 will work. 32 (float) and 64 (double) are supported on all targets; 80 2483 or 128 (different flavors of long double) are also supported on some 2484 targets. 2485``a:<abi>:<pref>`` 2486 This specifies the alignment for an object of aggregate type. 2487``F<type><abi>`` 2488 This specifies the alignment for function pointers. 2489 The options for ``<type>`` are: 2490 2491 * ``i``: The alignment of function pointers is independent of the alignment 2492 of functions, and is a multiple of ``<abi>``. 2493 * ``n``: The alignment of function pointers is a multiple of the explicit 2494 alignment specified on the function, and is a multiple of ``<abi>``. 2495``m:<mangling>`` 2496 If present, specifies that llvm names are mangled in the output. Symbols 2497 prefixed with the mangling escape character ``\01`` are passed through 2498 directly to the assembler without the escape character. The mangling style 2499 options are 2500 2501 * ``e``: ELF mangling: Private symbols get a ``.L`` prefix. 2502 * ``m``: Mips mangling: Private symbols get a ``$`` prefix. 2503 * ``o``: Mach-O mangling: Private symbols get ``L`` prefix. Other 2504 symbols get a ``_`` prefix. 2505 * ``x``: Windows x86 COFF mangling: Private symbols get the usual prefix. 2506 Regular C symbols get a ``_`` prefix. Functions with ``__stdcall``, 2507 ``__fastcall``, and ``__vectorcall`` have custom mangling that appends 2508 ``@N`` where N is the number of bytes used to pass parameters. C++ symbols 2509 starting with ``?`` are not mangled in any way. 2510 * ``w``: Windows COFF mangling: Similar to ``x``, except that normal C 2511 symbols do not receive a ``_`` prefix. 2512 * ``a``: XCOFF mangling: Private symbols get a ``L..`` prefix. 2513``n<size1>:<size2>:<size3>...`` 2514 This specifies a set of native integer widths for the target CPU in 2515 bits. For example, it might contain ``n32`` for 32-bit PowerPC, 2516 ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of 2517 this set are considered to support most general arithmetic operations 2518 efficiently. 2519``ni:<address space0>:<address space1>:<address space2>...`` 2520 This specifies pointer types with the specified address spaces 2521 as :ref:`Non-Integral Pointer Type <nointptrtype>` s. The ``0`` 2522 address space cannot be specified as non-integral. 2523 2524On every specification that takes a ``<abi>:<pref>``, specifying the 2525``<pref>`` alignment is optional. If omitted, the preceding ``:`` 2526should be omitted too and ``<pref>`` will be equal to ``<abi>``. 2527 2528When constructing the data layout for a given target, LLVM starts with a 2529default set of specifications which are then (possibly) overridden by 2530the specifications in the ``datalayout`` keyword. The default 2531specifications are given in this list: 2532 2533- ``E`` - big endian 2534- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment. 2535- ``p[n]:64:64:64`` - Other address spaces are assumed to be the 2536 same as the default address space. 2537- ``S0`` - natural stack alignment is unspecified 2538- ``i1:8:8`` - i1 is 8-bit (byte) aligned 2539- ``i8:8:8`` - i8 is 8-bit (byte) aligned 2540- ``i16:16:16`` - i16 is 16-bit aligned 2541- ``i32:32:32`` - i32 is 32-bit aligned 2542- ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred 2543 alignment of 64-bits 2544- ``f16:16:16`` - half is 16-bit aligned 2545- ``f32:32:32`` - float is 32-bit aligned 2546- ``f64:64:64`` - double is 64-bit aligned 2547- ``f128:128:128`` - quad is 128-bit aligned 2548- ``v64:64:64`` - 64-bit vector is 64-bit aligned 2549- ``v128:128:128`` - 128-bit vector is 128-bit aligned 2550- ``a:0:64`` - aggregates are 64-bit aligned 2551 2552When LLVM is determining the alignment for a given type, it uses the 2553following rules: 2554 2555#. If the type sought is an exact match for one of the specifications, 2556 that specification is used. 2557#. If no match is found, and the type sought is an integer type, then 2558 the smallest integer type that is larger than the bitwidth of the 2559 sought type is used. If none of the specifications are larger than 2560 the bitwidth then the largest integer type is used. For example, 2561 given the default specifications above, the i7 type will use the 2562 alignment of i8 (next largest) while both i65 and i256 will use the 2563 alignment of i64 (largest specified). 2564#. If no match is found, and the type sought is a vector type, then the 2565 largest vector type that is smaller than the sought vector type will 2566 be used as a fall back. This happens because <128 x double> can be 2567 implemented in terms of 64 <2 x double>, for example. 2568 2569The function of the data layout string may not be what you expect. 2570Notably, this is not a specification from the frontend of what alignment 2571the code generator should use. 2572 2573Instead, if specified, the target data layout is required to match what 2574the ultimate *code generator* expects. This string is used by the 2575mid-level optimizers to improve code, and this only works if it matches 2576what the ultimate code generator uses. There is no way to generate IR 2577that does not embed this target-specific detail into the IR. If you 2578don't specify the string, the default specifications will be used to 2579generate a Data Layout and the optimization phases will operate 2580accordingly and introduce target specificity into the IR with respect to 2581these default specifications. 2582 2583.. _langref_triple: 2584 2585Target Triple 2586------------- 2587 2588A module may specify a target triple string that describes the target 2589host. The syntax for the target triple is simply: 2590 2591.. code-block:: llvm 2592 2593 target triple = "x86_64-apple-macosx10.7.0" 2594 2595The *target triple* string consists of a series of identifiers delimited 2596by the minus sign character ('-'). The canonical forms are: 2597 2598:: 2599 2600 ARCHITECTURE-VENDOR-OPERATING_SYSTEM 2601 ARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT 2602 2603This information is passed along to the backend so that it generates 2604code for the proper architecture. It's possible to override this on the 2605command line with the ``-mtriple`` command line option. 2606 2607.. _objectlifetime: 2608 2609Object Lifetime 2610---------------------- 2611 2612A memory object, or simply object, is a region of a memory space that is 2613reserved by a memory allocation such as :ref:`alloca <i_alloca>`, heap 2614allocation calls, and global variable definitions. 2615Once it is allocated, the bytes stored in the region can only be read or written 2616through a pointer that is :ref:`based on <pointeraliasing>` the allocation 2617value. 2618If a pointer that is not based on the object tries to read or write to the 2619object, it is undefined behavior. 2620 2621A lifetime of a memory object is a property that decides its accessibility. 2622Unless stated otherwise, a memory object is alive since its allocation, and 2623dead after its deallocation. 2624It is undefined behavior to access a memory object that isn't alive, but 2625operations that don't dereference it such as 2626:ref:`getelementptr <i_getelementptr>`, :ref:`ptrtoint <i_ptrtoint>` and 2627:ref:`icmp <i_icmp>` return a valid result. 2628This explains code motion of these instructions across operations that 2629impact the object's lifetime. 2630A stack object's lifetime can be explicitly specified using 2631:ref:`llvm.lifetime.start <int_lifestart>` and 2632:ref:`llvm.lifetime.end <int_lifeend>` intrinsic function calls. 2633 2634.. _pointeraliasing: 2635 2636Pointer Aliasing Rules 2637---------------------- 2638 2639Any memory access must be done through a pointer value associated with 2640an address range of the memory access, otherwise the behavior is 2641undefined. Pointer values are associated with address ranges according 2642to the following rules: 2643 2644- A pointer value is associated with the addresses associated with any 2645 value it is *based* on. 2646- An address of a global variable is associated with the address range 2647 of the variable's storage. 2648- The result value of an allocation instruction is associated with the 2649 address range of the allocated storage. 2650- A null pointer in the default address-space is associated with no 2651 address. 2652- An :ref:`undef value <undefvalues>` in *any* address-space is 2653 associated with no address. 2654- An integer constant other than zero or a pointer value returned from 2655 a function not defined within LLVM may be associated with address 2656 ranges allocated through mechanisms other than those provided by 2657 LLVM. Such ranges shall not overlap with any ranges of addresses 2658 allocated by mechanisms provided by LLVM. 2659 2660A pointer value is *based* on another pointer value according to the 2661following rules: 2662 2663- A pointer value formed from a scalar ``getelementptr`` operation is *based* on 2664 the pointer-typed operand of the ``getelementptr``. 2665- The pointer in lane *l* of the result of a vector ``getelementptr`` operation 2666 is *based* on the pointer in lane *l* of the vector-of-pointers-typed operand 2667 of the ``getelementptr``. 2668- The result value of a ``bitcast`` is *based* on the operand of the 2669 ``bitcast``. 2670- A pointer value formed by an ``inttoptr`` is *based* on all pointer 2671 values that contribute (directly or indirectly) to the computation of 2672 the pointer's value. 2673- The "*based* on" relationship is transitive. 2674 2675Note that this definition of *"based"* is intentionally similar to the 2676definition of *"based"* in C99, though it is slightly weaker. 2677 2678LLVM IR does not associate types with memory. The result type of a 2679``load`` merely indicates the size and alignment of the memory from 2680which to load, as well as the interpretation of the value. The first 2681operand type of a ``store`` similarly only indicates the size and 2682alignment of the store. 2683 2684Consequently, type-based alias analysis, aka TBAA, aka 2685``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR. 2686:ref:`Metadata <metadata>` may be used to encode additional information 2687which specialized optimization passes may use to implement type-based 2688alias analysis. 2689 2690.. _pointercapture: 2691 2692Pointer Capture 2693--------------- 2694 2695Given a function call and a pointer that is passed as an argument or stored in 2696the memory before the call, a pointer is *captured* by the call if it makes a 2697copy of any part of the pointer that outlives the call. 2698To be precise, a pointer is captured if one or more of the following conditions 2699hold: 2700 27011. The call stores any bit of the pointer carrying information into a place, 2702 and the stored bits can be read from the place by the caller after this call 2703 exits. 2704 2705.. code-block:: llvm 2706 2707 @glb = global i8* null 2708 @glb2 = global i8* null 2709 @glb3 = global i8* null 2710 @glbi = global i32 0 2711 2712 define i8* @f(i8* %a, i8* %b, i8* %c, i8* %d, i8* %e) { 2713 store i8* %a, i8** @glb ; %a is captured by this call 2714 2715 store i8* %b, i8** @glb2 ; %b isn't captured because the stored value is overwritten by the store below 2716 store i8* null, i8** @glb2 2717 2718 store i8* %c, i8** @glb3 2719 call void @g() ; If @g makes a copy of %c that outlives this call (@f), %c is captured 2720 store i8* null, i8** @glb3 2721 2722 %i = ptrtoint i8* %d to i64 2723 %j = trunc i64 %i to i32 2724 store i32 %j, i32* @glbi ; %d is captured 2725 2726 ret i8* %e ; %e is captured 2727 } 2728 27292. The call stores any bit of the pointer carrying information into a place, 2730 and the stored bits can be safely read from the place by another thread via 2731 synchronization. 2732 2733.. code-block:: llvm 2734 2735 @lock = global i1 true 2736 2737 define void @f(i8* %a) { 2738 store i8* %a, i8** @glb 2739 store atomic i1 false, i1* @lock release ; %a is captured because another thread can safely read @glb 2740 store i8* null, i8** @glb 2741 ret void 2742 } 2743 27443. The call's behavior depends on any bit of the pointer carrying information. 2745 2746.. code-block:: llvm 2747 2748 @glb = global i8 0 2749 2750 define void @f(i8* %a) { 2751 %c = icmp eq i8* %a, @glb 2752 br i1 %c, label %BB_EXIT, label %BB_CONTINUE ; escapes %a 2753 BB_EXIT: 2754 call void @exit() 2755 unreachable 2756 BB_CONTINUE: 2757 ret void 2758 } 2759 27604. The pointer is used in a volatile access as its address. 2761 2762 2763.. _volatile: 2764 2765Volatile Memory Accesses 2766------------------------ 2767 2768Certain memory accesses, such as :ref:`load <i_load>`'s, 2769:ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be 2770marked ``volatile``. The optimizers must not change the number of 2771volatile operations or change their order of execution relative to other 2772volatile operations. The optimizers *may* change the order of volatile 2773operations relative to non-volatile operations. This is not Java's 2774"volatile" and has no cross-thread synchronization behavior. 2775 2776A volatile load or store may have additional target-specific semantics. 2777Any volatile operation can have side effects, and any volatile operation 2778can read and/or modify state which is not accessible via a regular load 2779or store in this module. Volatile operations may use addresses which do 2780not point to memory (like MMIO registers). This means the compiler may 2781not use a volatile operation to prove a non-volatile access to that 2782address has defined behavior. 2783 2784The allowed side-effects for volatile accesses are limited. If a 2785non-volatile store to a given address would be legal, a volatile 2786operation may modify the memory at that address. A volatile operation 2787may not modify any other memory accessible by the module being compiled. 2788A volatile operation may not call any code in the current module. 2789 2790The compiler may assume execution will continue after a volatile operation, 2791so operations which modify memory or may have undefined behavior can be 2792hoisted past a volatile operation. 2793 2794IR-level volatile loads and stores cannot safely be optimized into llvm.memcpy 2795or llvm.memmove intrinsics even when those intrinsics are flagged volatile. 2796Likewise, the backend should never split or merge target-legal volatile 2797load/store instructions. Similarly, IR-level volatile loads and stores cannot 2798change from integer to floating-point or vice versa. 2799 2800.. admonition:: Rationale 2801 2802 Platforms may rely on volatile loads and stores of natively supported 2803 data width to be executed as single instruction. For example, in C 2804 this holds for an l-value of volatile primitive type with native 2805 hardware support, but not necessarily for aggregate types. The 2806 frontend upholds these expectations, which are intentionally 2807 unspecified in the IR. The rules above ensure that IR transformations 2808 do not violate the frontend's contract with the language. 2809 2810.. _memmodel: 2811 2812Memory Model for Concurrent Operations 2813-------------------------------------- 2814 2815The LLVM IR does not define any way to start parallel threads of 2816execution or to register signal handlers. Nonetheless, there are 2817platform-specific ways to create them, and we define LLVM IR's behavior 2818in their presence. This model is inspired by the C++0x memory model. 2819 2820For a more informal introduction to this model, see the :doc:`Atomics`. 2821 2822We define a *happens-before* partial order as the least partial order 2823that 2824 2825- Is a superset of single-thread program order, and 2826- When a *synchronizes-with* ``b``, includes an edge from ``a`` to 2827 ``b``. *Synchronizes-with* pairs are introduced by platform-specific 2828 techniques, like pthread locks, thread creation, thread joining, 2829 etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering 2830 Constraints <ordering>`). 2831 2832Note that program order does not introduce *happens-before* edges 2833between a thread and signals executing inside that thread. 2834 2835Every (defined) read operation (load instructions, memcpy, atomic 2836loads/read-modify-writes, etc.) R reads a series of bytes written by 2837(defined) write operations (store instructions, atomic 2838stores/read-modify-writes, memcpy, etc.). For the purposes of this 2839section, initialized globals are considered to have a write of the 2840initializer which is atomic and happens before any other read or write 2841of the memory in question. For each byte of a read R, R\ :sub:`byte` 2842may see any write to the same byte, except: 2843 2844- If write\ :sub:`1` happens before write\ :sub:`2`, and 2845 write\ :sub:`2` happens before R\ :sub:`byte`, then 2846 R\ :sub:`byte` does not see write\ :sub:`1`. 2847- If R\ :sub:`byte` happens before write\ :sub:`3`, then 2848 R\ :sub:`byte` does not see write\ :sub:`3`. 2849 2850Given that definition, R\ :sub:`byte` is defined as follows: 2851 2852- If R is volatile, the result is target-dependent. (Volatile is 2853 supposed to give guarantees which can support ``sig_atomic_t`` in 2854 C/C++, and may be used for accesses to addresses that do not behave 2855 like normal memory. It does not generally provide cross-thread 2856 synchronization.) 2857- Otherwise, if there is no write to the same byte that happens before 2858 R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte. 2859- Otherwise, if R\ :sub:`byte` may see exactly one write, 2860 R\ :sub:`byte` returns the value written by that write. 2861- Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may 2862 see are atomic, it chooses one of the values written. See the :ref:`Atomic 2863 Memory Ordering Constraints <ordering>` section for additional 2864 constraints on how the choice is made. 2865- Otherwise R\ :sub:`byte` returns ``undef``. 2866 2867R returns the value composed of the series of bytes it read. This 2868implies that some bytes within the value may be ``undef`` **without** 2869the entire value being ``undef``. Note that this only defines the 2870semantics of the operation; it doesn't mean that targets will emit more 2871than one instruction to read the series of bytes. 2872 2873Note that in cases where none of the atomic intrinsics are used, this 2874model places only one restriction on IR transformations on top of what 2875is required for single-threaded execution: introducing a store to a byte 2876which might not otherwise be stored is not allowed in general. 2877(Specifically, in the case where another thread might write to and read 2878from an address, introducing a store can change a load that may see 2879exactly one write into a load that may see multiple writes.) 2880 2881.. _ordering: 2882 2883Atomic Memory Ordering Constraints 2884---------------------------------- 2885 2886Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`, 2887:ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`, 2888:ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take 2889ordering parameters that determine which other atomic instructions on 2890the same address they *synchronize with*. These semantics are borrowed 2891from Java and C++0x, but are somewhat more colloquial. If these 2892descriptions aren't precise enough, check those specs (see spec 2893references in the :doc:`atomics guide <Atomics>`). 2894:ref:`fence <i_fence>` instructions treat these orderings somewhat 2895differently since they don't take an address. See that instruction's 2896documentation for details. 2897 2898For a simpler introduction to the ordering constraints, see the 2899:doc:`Atomics`. 2900 2901``unordered`` 2902 The set of values that can be read is governed by the happens-before 2903 partial order. A value cannot be read unless some operation wrote 2904 it. This is intended to provide a guarantee strong enough to model 2905 Java's non-volatile shared variables. This ordering cannot be 2906 specified for read-modify-write operations; it is not strong enough 2907 to make them atomic in any interesting way. 2908``monotonic`` 2909 In addition to the guarantees of ``unordered``, there is a single 2910 total order for modifications by ``monotonic`` operations on each 2911 address. All modification orders must be compatible with the 2912 happens-before order. There is no guarantee that the modification 2913 orders can be combined to a global total order for the whole program 2914 (and this often will not be possible). The read in an atomic 2915 read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and 2916 :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification 2917 order immediately before the value it writes. If one atomic read 2918 happens before another atomic read of the same address, the later 2919 read must see the same value or a later value in the address's 2920 modification order. This disallows reordering of ``monotonic`` (or 2921 stronger) operations on the same address. If an address is written 2922 ``monotonic``-ally by one thread, and other threads ``monotonic``-ally 2923 read that address repeatedly, the other threads must eventually see 2924 the write. This corresponds to the C++0x/C1x 2925 ``memory_order_relaxed``. 2926``acquire`` 2927 In addition to the guarantees of ``monotonic``, a 2928 *synchronizes-with* edge may be formed with a ``release`` operation. 2929 This is intended to model C++'s ``memory_order_acquire``. 2930``release`` 2931 In addition to the guarantees of ``monotonic``, if this operation 2932 writes a value which is subsequently read by an ``acquire`` 2933 operation, it *synchronizes-with* that operation. (This isn't a 2934 complete description; see the C++0x definition of a release 2935 sequence.) This corresponds to the C++0x/C1x 2936 ``memory_order_release``. 2937``acq_rel`` (acquire+release) 2938 Acts as both an ``acquire`` and ``release`` operation on its 2939 address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``. 2940``seq_cst`` (sequentially consistent) 2941 In addition to the guarantees of ``acq_rel`` (``acquire`` for an 2942 operation that only reads, ``release`` for an operation that only 2943 writes), there is a global total order on all 2944 sequentially-consistent operations on all addresses, which is 2945 consistent with the *happens-before* partial order and with the 2946 modification orders of all the affected addresses. Each 2947 sequentially-consistent read sees the last preceding write to the 2948 same address in this global order. This corresponds to the C++0x/C1x 2949 ``memory_order_seq_cst`` and Java volatile. 2950 2951.. _syncscope: 2952 2953If an atomic operation is marked ``syncscope("singlethread")``, it only 2954*synchronizes with* and only participates in the seq\_cst total orderings of 2955other operations running in the same thread (for example, in signal handlers). 2956 2957If an atomic operation is marked ``syncscope("<target-scope>")``, where 2958``<target-scope>`` is a target specific synchronization scope, then it is target 2959dependent if it *synchronizes with* and participates in the seq\_cst total 2960orderings of other operations. 2961 2962Otherwise, an atomic operation that is not marked ``syncscope("singlethread")`` 2963or ``syncscope("<target-scope>")`` *synchronizes with* and participates in the 2964seq\_cst total orderings of other operations that are not marked 2965``syncscope("singlethread")`` or ``syncscope("<target-scope>")``. 2966 2967.. _floatenv: 2968 2969Floating-Point Environment 2970-------------------------- 2971 2972The default LLVM floating-point environment assumes that floating-point 2973instructions do not have side effects. Results assume the round-to-nearest 2974rounding mode. No floating-point exception state is maintained in this 2975environment. Therefore, there is no attempt to create or preserve invalid 2976operation (SNaN) or division-by-zero exceptions. 2977 2978The benefit of this exception-free assumption is that floating-point 2979operations may be speculated freely without any other fast-math relaxations 2980to the floating-point model. 2981 2982Code that requires different behavior than this should use the 2983:ref:`Constrained Floating-Point Intrinsics <constrainedfp>`. 2984 2985.. _fastmath: 2986 2987Fast-Math Flags 2988--------------- 2989 2990LLVM IR floating-point operations (:ref:`fneg <i_fneg>`, :ref:`fadd <i_fadd>`, 2991:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`, 2992:ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`), :ref:`phi <i_phi>`, 2993:ref:`select <i_select>` and :ref:`call <i_call>` 2994may use the following flags to enable otherwise unsafe 2995floating-point transformations. 2996 2997``nnan`` 2998 No NaNs - Allow optimizations to assume the arguments and result are not 2999 NaN. If an argument is a nan, or the result would be a nan, it produces 3000 a :ref:`poison value <poisonvalues>` instead. 3001 3002``ninf`` 3003 No Infs - Allow optimizations to assume the arguments and result are not 3004 +/-Inf. If an argument is +/-Inf, or the result would be +/-Inf, it 3005 produces a :ref:`poison value <poisonvalues>` instead. 3006 3007``nsz`` 3008 No Signed Zeros - Allow optimizations to treat the sign of a zero 3009 argument or result as insignificant. This does not imply that -0.0 3010 is poison and/or guaranteed to not exist in the operation. 3011 3012``arcp`` 3013 Allow Reciprocal - Allow optimizations to use the reciprocal of an 3014 argument rather than perform division. 3015 3016``contract`` 3017 Allow floating-point contraction (e.g. fusing a multiply followed by an 3018 addition into a fused multiply-and-add). This does not enable reassociating 3019 to form arbitrary contractions. For example, ``(a*b) + (c*d) + e`` can not 3020 be transformed into ``(a*b) + ((c*d) + e)`` to create two fma operations. 3021 3022``afn`` 3023 Approximate functions - Allow substitution of approximate calculations for 3024 functions (sin, log, sqrt, etc). See floating-point intrinsic definitions 3025 for places where this can apply to LLVM's intrinsic math functions. 3026 3027``reassoc`` 3028 Allow reassociation transformations for floating-point instructions. 3029 This may dramatically change results in floating-point. 3030 3031``fast`` 3032 This flag implies all of the others. 3033 3034.. _uselistorder: 3035 3036Use-list Order Directives 3037------------------------- 3038 3039Use-list directives encode the in-memory order of each use-list, allowing the 3040order to be recreated. ``<order-indexes>`` is a comma-separated list of 3041indexes that are assigned to the referenced value's uses. The referenced 3042value's use-list is immediately sorted by these indexes. 3043 3044Use-list directives may appear at function scope or global scope. They are not 3045instructions, and have no effect on the semantics of the IR. When they're at 3046function scope, they must appear after the terminator of the final basic block. 3047 3048If basic blocks have their address taken via ``blockaddress()`` expressions, 3049``uselistorder_bb`` can be used to reorder their use-lists from outside their 3050function's scope. 3051 3052:Syntax: 3053 3054:: 3055 3056 uselistorder <ty> <value>, { <order-indexes> } 3057 uselistorder_bb @function, %block { <order-indexes> } 3058 3059:Examples: 3060 3061:: 3062 3063 define void @foo(i32 %arg1, i32 %arg2) { 3064 entry: 3065 ; ... instructions ... 3066 bb: 3067 ; ... instructions ... 3068 3069 ; At function scope. 3070 uselistorder i32 %arg1, { 1, 0, 2 } 3071 uselistorder label %bb, { 1, 0 } 3072 } 3073 3074 ; At global scope. 3075 uselistorder i32* @global, { 1, 2, 0 } 3076 uselistorder i32 7, { 1, 0 } 3077 uselistorder i32 (i32) @bar, { 1, 0 } 3078 uselistorder_bb @foo, %bb, { 5, 1, 3, 2, 0, 4 } 3079 3080.. _source_filename: 3081 3082Source Filename 3083--------------- 3084 3085The *source filename* string is set to the original module identifier, 3086which will be the name of the compiled source file when compiling from 3087source through the clang front end, for example. It is then preserved through 3088the IR and bitcode. 3089 3090This is currently necessary to generate a consistent unique global 3091identifier for local functions used in profile data, which prepends the 3092source file name to the local function name. 3093 3094The syntax for the source file name is simply: 3095 3096.. code-block:: text 3097 3098 source_filename = "/path/to/source.c" 3099 3100.. _typesystem: 3101 3102Type System 3103=========== 3104 3105The LLVM type system is one of the most important features of the 3106intermediate representation. Being typed enables a number of 3107optimizations to be performed on the intermediate representation 3108directly, without having to do extra analyses on the side before the 3109transformation. A strong type system makes it easier to read the 3110generated code and enables novel analyses and transformations that are 3111not feasible to perform on normal three address code representations. 3112 3113.. _t_void: 3114 3115Void Type 3116--------- 3117 3118:Overview: 3119 3120 3121The void type does not represent any value and has no size. 3122 3123:Syntax: 3124 3125 3126:: 3127 3128 void 3129 3130 3131.. _t_function: 3132 3133Function Type 3134------------- 3135 3136:Overview: 3137 3138 3139The function type can be thought of as a function signature. It consists of a 3140return type and a list of formal parameter types. The return type of a function 3141type is a void type or first class type --- except for :ref:`label <t_label>` 3142and :ref:`metadata <t_metadata>` types. 3143 3144:Syntax: 3145 3146:: 3147 3148 <returntype> (<parameter list>) 3149 3150...where '``<parameter list>``' is a comma-separated list of type 3151specifiers. Optionally, the parameter list may include a type ``...``, which 3152indicates that the function takes a variable number of arguments. Variable 3153argument functions can access their arguments with the :ref:`variable argument 3154handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type 3155except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`. 3156 3157:Examples: 3158 3159+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3160| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` | 3161+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3162| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. | 3163+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3164| ``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. | 3165+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3166| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values | 3167+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3168 3169.. _t_firstclass: 3170 3171First Class Types 3172----------------- 3173 3174The :ref:`first class <t_firstclass>` types are perhaps the most important. 3175Values of these types are the only ones which can be produced by 3176instructions. 3177 3178.. _t_single_value: 3179 3180Single Value Types 3181^^^^^^^^^^^^^^^^^^ 3182 3183These are the types that are valid in registers from CodeGen's perspective. 3184 3185.. _t_integer: 3186 3187Integer Type 3188"""""""""""" 3189 3190:Overview: 3191 3192The integer type is a very simple type that simply specifies an 3193arbitrary bit width for the integer type desired. Any bit width from 1 3194bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified. 3195 3196:Syntax: 3197 3198:: 3199 3200 iN 3201 3202The number of bits the integer will occupy is specified by the ``N`` 3203value. 3204 3205Examples: 3206********* 3207 3208+----------------+------------------------------------------------+ 3209| ``i1`` | a single-bit integer. | 3210+----------------+------------------------------------------------+ 3211| ``i32`` | a 32-bit integer. | 3212+----------------+------------------------------------------------+ 3213| ``i1942652`` | a really big integer of over 1 million bits. | 3214+----------------+------------------------------------------------+ 3215 3216.. _t_floating: 3217 3218Floating-Point Types 3219"""""""""""""""""""" 3220 3221.. list-table:: 3222 :header-rows: 1 3223 3224 * - Type 3225 - Description 3226 3227 * - ``half`` 3228 - 16-bit floating-point value 3229 3230 * - ``bfloat`` 3231 - 16-bit "brain" floating-point value (7-bit significand). Provides the 3232 same number of exponent bits as ``float``, so that it matches its dynamic 3233 range, but with greatly reduced precision. Used in Intel's AVX-512 BF16 3234 extensions and Arm's ARMv8.6-A extensions, among others. 3235 3236 * - ``float`` 3237 - 32-bit floating-point value 3238 3239 * - ``double`` 3240 - 64-bit floating-point value 3241 3242 * - ``fp128`` 3243 - 128-bit floating-point value (113-bit significand) 3244 3245 * - ``x86_fp80`` 3246 - 80-bit floating-point value (X87) 3247 3248 * - ``ppc_fp128`` 3249 - 128-bit floating-point value (two 64-bits) 3250 3251The binary format of half, float, double, and fp128 correspond to the 3252IEEE-754-2008 specifications for binary16, binary32, binary64, and binary128 3253respectively. 3254 3255X86_amx Type 3256"""""""""""" 3257 3258:Overview: 3259 3260The x86_amx type represents a value held in an AMX tile register on an x86 3261machine. The operations allowed on it are quite limited. Only few intrinsics 3262are allowed: stride load and store, zero and dot product. No instruction is 3263allowed for this type. There are no arguments, arrays, pointers, vectors 3264or constants of this type. 3265 3266:Syntax: 3267 3268:: 3269 3270 x86_amx 3271 3272 3273X86_mmx Type 3274"""""""""""" 3275 3276:Overview: 3277 3278The x86_mmx type represents a value held in an MMX register on an x86 3279machine. The operations allowed on it are quite limited: parameters and 3280return values, load and store, and bitcast. User-specified MMX 3281instructions are represented as intrinsic or asm calls with arguments 3282and/or results of this type. There are no arrays, vectors or constants 3283of this type. 3284 3285:Syntax: 3286 3287:: 3288 3289 x86_mmx 3290 3291 3292.. _t_pointer: 3293 3294Pointer Type 3295"""""""""""" 3296 3297:Overview: 3298 3299The pointer type is used to specify memory locations. Pointers are 3300commonly used to reference objects in memory. 3301 3302Pointer types may have an optional address space attribute defining the 3303numbered address space where the pointed-to object resides. The default 3304address space is number zero. The semantics of non-zero address spaces 3305are target-specific. 3306 3307Note that LLVM does not permit pointers to void (``void*``) nor does it 3308permit pointers to labels (``label*``). Use ``i8*`` instead. 3309 3310:Syntax: 3311 3312:: 3313 3314 <type> * 3315 3316:Examples: 3317 3318+-------------------------+--------------------------------------------------------------------------------------------------------------+ 3319| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. | 3320+-------------------------+--------------------------------------------------------------------------------------------------------------+ 3321| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. | 3322+-------------------------+--------------------------------------------------------------------------------------------------------------+ 3323| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. | 3324+-------------------------+--------------------------------------------------------------------------------------------------------------+ 3325 3326.. _t_vector: 3327 3328Vector Type 3329""""""""""" 3330 3331:Overview: 3332 3333A vector type is a simple derived type that represents a vector of 3334elements. Vector types are used when multiple primitive data are 3335operated in parallel using a single instruction (SIMD). A vector type 3336requires a size (number of elements), an underlying primitive data type, 3337and a scalable property to represent vectors where the exact hardware 3338vector length is unknown at compile time. Vector types are considered 3339:ref:`first class <t_firstclass>`. 3340 3341:Memory Layout: 3342 3343In general vector elements are laid out in memory in the same way as 3344:ref:`array types <t_array>`. Such an anology works fine as long as the vector 3345elements are byte sized. However, when the elements of the vector aren't byte 3346sized it gets a bit more complicated. One way to describe the layout is by 3347describing what happens when a vector such as <N x iM> is bitcasted to an 3348integer type with N*M bits, and then following the rules for storing such an 3349integer to memory. 3350 3351A bitcast from a vector type to a scalar integer type will see the elements 3352being packed together (without padding). The order in which elements are 3353inserted in the integer depends on endianess. For little endian element zero 3354is put in the least significant bits of the integer, and for big endian 3355element zero is put in the most significant bits. 3356 3357Using a vector such as ``<i4 1, i4 2, i4 3, i4 5>`` as an example, together 3358with the analogy that we can replace a vector store by a bitcast followed by 3359an integer store, we get this for big endian: 3360 3361.. code-block:: llvm 3362 3363 %val = bitcast <4 x i4> <i4 1, i4 2, i4 3, i4 5> to i16 3364 3365 ; Bitcasting from a vector to an integral type can be seen as 3366 ; concatenating the values: 3367 ; %val now has the hexadecimal value 0x1235. 3368 3369 store i16 %val, i16* %ptr 3370 3371 ; In memory the content will be (8-bit addressing): 3372 ; 3373 ; [%ptr + 0]: 00010010 (0x12) 3374 ; [%ptr + 1]: 00110101 (0x35) 3375 3376The same example for little endian: 3377 3378.. code-block:: llvm 3379 3380 %val = bitcast <4 x i4> <i4 1, i4 2, i4 3, i4 5> to i16 3381 3382 ; Bitcasting from a vector to an integral type can be seen as 3383 ; concatenating the values: 3384 ; %val now has the hexadecimal value 0x5321. 3385 3386 store i16 %val, i16* %ptr 3387 3388 ; In memory the content will be (8-bit addressing): 3389 ; 3390 ; [%ptr + 0]: 01010011 (0x53) 3391 ; [%ptr + 1]: 00100001 (0x21) 3392 3393When ``<N*M>`` isn't evenly divisible by the byte size the exact memory layout 3394is unspecified (just like it is for an integral type of the same size). This 3395is because different targets could put the padding at different positions when 3396the type size is smaller than the type's store size. 3397 3398:Syntax: 3399 3400:: 3401 3402 < <# elements> x <elementtype> > ; Fixed-length vector 3403 < vscale x <# elements> x <elementtype> > ; Scalable vector 3404 3405The number of elements is a constant integer value larger than 0; 3406elementtype may be any integer, floating-point or pointer type. Vectors 3407of size zero are not allowed. For scalable vectors, the total number of 3408elements is a constant multiple (called vscale) of the specified number 3409of elements; vscale is a positive integer that is unknown at compile time 3410and the same hardware-dependent constant for all scalable vectors at run 3411time. The size of a specific scalable vector type is thus constant within 3412IR, even if the exact size in bytes cannot be determined until run time. 3413 3414:Examples: 3415 3416+------------------------+----------------------------------------------------+ 3417| ``<4 x i32>`` | Vector of 4 32-bit integer values. | 3418+------------------------+----------------------------------------------------+ 3419| ``<8 x float>`` | Vector of 8 32-bit floating-point values. | 3420+------------------------+----------------------------------------------------+ 3421| ``<2 x i64>`` | Vector of 2 64-bit integer values. | 3422+------------------------+----------------------------------------------------+ 3423| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. | 3424+------------------------+----------------------------------------------------+ 3425| ``<vscale x 4 x i32>`` | Vector with a multiple of 4 32-bit integer values. | 3426+------------------------+----------------------------------------------------+ 3427 3428.. _t_label: 3429 3430Label Type 3431^^^^^^^^^^ 3432 3433:Overview: 3434 3435The label type represents code labels. 3436 3437:Syntax: 3438 3439:: 3440 3441 label 3442 3443.. _t_token: 3444 3445Token Type 3446^^^^^^^^^^ 3447 3448:Overview: 3449 3450The token type is used when a value is associated with an instruction 3451but all uses of the value must not attempt to introspect or obscure it. 3452As such, it is not appropriate to have a :ref:`phi <i_phi>` or 3453:ref:`select <i_select>` of type token. 3454 3455:Syntax: 3456 3457:: 3458 3459 token 3460 3461 3462 3463.. _t_metadata: 3464 3465Metadata Type 3466^^^^^^^^^^^^^ 3467 3468:Overview: 3469 3470The metadata type represents embedded metadata. No derived types may be 3471created from metadata except for :ref:`function <t_function>` arguments. 3472 3473:Syntax: 3474 3475:: 3476 3477 metadata 3478 3479.. _t_aggregate: 3480 3481Aggregate Types 3482^^^^^^^^^^^^^^^ 3483 3484Aggregate Types are a subset of derived types that can contain multiple 3485member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are 3486aggregate types. :ref:`Vectors <t_vector>` are not considered to be 3487aggregate types. 3488 3489.. _t_array: 3490 3491Array Type 3492"""""""""" 3493 3494:Overview: 3495 3496The array type is a very simple derived type that arranges elements 3497sequentially in memory. The array type requires a size (number of 3498elements) and an underlying data type. 3499 3500:Syntax: 3501 3502:: 3503 3504 [<# elements> x <elementtype>] 3505 3506The number of elements is a constant integer value; ``elementtype`` may 3507be any type with a size. 3508 3509:Examples: 3510 3511+------------------+--------------------------------------+ 3512| ``[40 x i32]`` | Array of 40 32-bit integer values. | 3513+------------------+--------------------------------------+ 3514| ``[41 x i32]`` | Array of 41 32-bit integer values. | 3515+------------------+--------------------------------------+ 3516| ``[4 x i8]`` | Array of 4 8-bit integer values. | 3517+------------------+--------------------------------------+ 3518 3519Here are some examples of multidimensional arrays: 3520 3521+-----------------------------+----------------------------------------------------------+ 3522| ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. | 3523+-----------------------------+----------------------------------------------------------+ 3524| ``[12 x [10 x float]]`` | 12x10 array of single precision floating-point values. | 3525+-----------------------------+----------------------------------------------------------+ 3526| ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. | 3527+-----------------------------+----------------------------------------------------------+ 3528 3529There is no restriction on indexing beyond the end of the array implied 3530by a static type (though there are restrictions on indexing beyond the 3531bounds of an allocated object in some cases). This means that 3532single-dimension 'variable sized array' addressing can be implemented in 3533LLVM with a zero length array type. An implementation of 'pascal style 3534arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for 3535example. 3536 3537.. _t_struct: 3538 3539Structure Type 3540"""""""""""""" 3541 3542:Overview: 3543 3544The structure type is used to represent a collection of data members 3545together in memory. The elements of a structure may be any type that has 3546a size. 3547 3548Structures in memory are accessed using '``load``' and '``store``' by 3549getting a pointer to a field with the '``getelementptr``' instruction. 3550Structures in registers are accessed using the '``extractvalue``' and 3551'``insertvalue``' instructions. 3552 3553Structures may optionally be "packed" structures, which indicate that 3554the alignment of the struct is one byte, and that there is no padding 3555between the elements. In non-packed structs, padding between field types 3556is inserted as defined by the DataLayout string in the module, which is 3557required to match what the underlying code generator expects. 3558 3559Structures can either be "literal" or "identified". A literal structure 3560is defined inline with other types (e.g. ``{i32, i32}*``) whereas 3561identified types are always defined at the top level with a name. 3562Literal types are uniqued by their contents and can never be recursive 3563or opaque since there is no way to write one. Identified types can be 3564recursive, can be opaqued, and are never uniqued. 3565 3566:Syntax: 3567 3568:: 3569 3570 %T1 = type { <type list> } ; Identified normal struct type 3571 %T2 = type <{ <type list> }> ; Identified packed struct type 3572 3573:Examples: 3574 3575+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3576| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values | 3577+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3578| ``{ 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``. | 3579+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3580| ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. | 3581+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3582 3583.. _t_opaque: 3584 3585Opaque Structure Types 3586"""""""""""""""""""""" 3587 3588:Overview: 3589 3590Opaque structure types are used to represent structure types that 3591do not have a body specified. This corresponds (for example) to the C 3592notion of a forward declared structure. They can be named (``%X``) or 3593unnamed (``%52``). 3594 3595:Syntax: 3596 3597:: 3598 3599 %X = type opaque 3600 %52 = type opaque 3601 3602:Examples: 3603 3604+--------------+-------------------+ 3605| ``opaque`` | An opaque type. | 3606+--------------+-------------------+ 3607 3608.. _constants: 3609 3610Constants 3611========= 3612 3613LLVM has several different basic types of constants. This section 3614describes them all and their syntax. 3615 3616Simple Constants 3617---------------- 3618 3619**Boolean constants** 3620 The two strings '``true``' and '``false``' are both valid constants 3621 of the ``i1`` type. 3622**Integer constants** 3623 Standard integers (such as '4') are constants of the 3624 :ref:`integer <t_integer>` type. Negative numbers may be used with 3625 integer types. 3626**Floating-point constants** 3627 Floating-point constants use standard decimal notation (e.g. 3628 123.421), exponential notation (e.g. 1.23421e+2), or a more precise 3629 hexadecimal notation (see below). The assembler requires the exact 3630 decimal value of a floating-point constant. For example, the 3631 assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating 3632 decimal in binary. Floating-point constants must have a 3633 :ref:`floating-point <t_floating>` type. 3634**Null pointer constants** 3635 The identifier '``null``' is recognized as a null pointer constant 3636 and must be of :ref:`pointer type <t_pointer>`. 3637**Token constants** 3638 The identifier '``none``' is recognized as an empty token constant 3639 and must be of :ref:`token type <t_token>`. 3640 3641The one non-intuitive notation for constants is the hexadecimal form of 3642floating-point constants. For example, the form 3643'``double 0x432ff973cafa8000``' is equivalent to (but harder to read 3644than) '``double 4.5e+15``'. The only time hexadecimal floating-point 3645constants are required (and the only time that they are generated by the 3646disassembler) is when a floating-point constant must be emitted but it 3647cannot be represented as a decimal floating-point number in a reasonable 3648number of digits. For example, NaN's, infinities, and other special 3649values are represented in their IEEE hexadecimal format so that assembly 3650and disassembly do not cause any bits to change in the constants. 3651 3652When using the hexadecimal form, constants of types bfloat, half, float, and 3653double are represented using the 16-digit form shown above (which matches the 3654IEEE754 representation for double); bfloat, half and float values must, however, 3655be exactly representable as bfloat, IEEE 754 half, and IEEE 754 single 3656precision respectively. Hexadecimal format is always used for long double, and 3657there are three forms of long double. The 80-bit format used by x86 is 3658represented as ``0xK`` followed by 20 hexadecimal digits. The 128-bit format 3659used by PowerPC (two adjacent doubles) is represented by ``0xM`` followed by 32 3660hexadecimal digits. The IEEE 128-bit format is represented by ``0xL`` followed 3661by 32 hexadecimal digits. Long doubles will only work if they match the long 3662double format on your target. The IEEE 16-bit format (half precision) is 3663represented by ``0xH`` followed by 4 hexadecimal digits. The bfloat 16-bit 3664format is represented by ``0xR`` followed by 4 hexadecimal digits. All 3665hexadecimal formats are big-endian (sign bit at the left). 3666 3667There are no constants of type x86_mmx and x86_amx. 3668 3669.. _complexconstants: 3670 3671Complex Constants 3672----------------- 3673 3674Complex constants are a (potentially recursive) combination of simple 3675constants and smaller complex constants. 3676 3677**Structure constants** 3678 Structure constants are represented with notation similar to 3679 structure type definitions (a comma separated list of elements, 3680 surrounded by braces (``{}``)). For example: 3681 "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as 3682 "``@G = external global i32``". Structure constants must have 3683 :ref:`structure type <t_struct>`, and the number and types of elements 3684 must match those specified by the type. 3685**Array constants** 3686 Array constants are represented with notation similar to array type 3687 definitions (a comma separated list of elements, surrounded by 3688 square brackets (``[]``)). For example: 3689 "``[ i32 42, i32 11, i32 74 ]``". Array constants must have 3690 :ref:`array type <t_array>`, and the number and types of elements must 3691 match those specified by the type. As a special case, character array 3692 constants may also be represented as a double-quoted string using the ``c`` 3693 prefix. For example: "``c"Hello World\0A\00"``". 3694**Vector constants** 3695 Vector constants are represented with notation similar to vector 3696 type definitions (a comma separated list of elements, surrounded by 3697 less-than/greater-than's (``<>``)). For example: 3698 "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants 3699 must have :ref:`vector type <t_vector>`, and the number and types of 3700 elements must match those specified by the type. 3701**Zero initialization** 3702 The string '``zeroinitializer``' can be used to zero initialize a 3703 value to zero of *any* type, including scalar and 3704 :ref:`aggregate <t_aggregate>` types. This is often used to avoid 3705 having to print large zero initializers (e.g. for large arrays) and 3706 is always exactly equivalent to using explicit zero initializers. 3707**Metadata node** 3708 A metadata node is a constant tuple without types. For example: 3709 "``!{!0, !{!2, !0}, !"test"}``". Metadata can reference constant values, 3710 for example: "``!{!0, i32 0, i8* @global, i64 (i64)* @function, !"str"}``". 3711 Unlike other typed constants that are meant to be interpreted as part of 3712 the instruction stream, metadata is a place to attach additional 3713 information such as debug info. 3714 3715Global Variable and Function Addresses 3716-------------------------------------- 3717 3718The addresses of :ref:`global variables <globalvars>` and 3719:ref:`functions <functionstructure>` are always implicitly valid 3720(link-time) constants. These constants are explicitly referenced when 3721the :ref:`identifier for the global <identifiers>` is used and always have 3722:ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM 3723file: 3724 3725.. code-block:: llvm 3726 3727 @X = global i32 17 3728 @Y = global i32 42 3729 @Z = global [2 x i32*] [ i32* @X, i32* @Y ] 3730 3731.. _undefvalues: 3732 3733Undefined Values 3734---------------- 3735 3736The string '``undef``' can be used anywhere a constant is expected, and 3737indicates that the user of the value may receive an unspecified 3738bit-pattern. Undefined values may be of any type (other than '``label``' 3739or '``void``') and be used anywhere a constant is permitted. 3740 3741Undefined values are useful because they indicate to the compiler that 3742the program is well defined no matter what value is used. This gives the 3743compiler more freedom to optimize. Here are some examples of 3744(potentially surprising) transformations that are valid (in pseudo IR): 3745 3746.. code-block:: llvm 3747 3748 %A = add %X, undef 3749 %B = sub %X, undef 3750 %C = xor %X, undef 3751 Safe: 3752 %A = undef 3753 %B = undef 3754 %C = undef 3755 3756This is safe because all of the output bits are affected by the undef 3757bits. Any output bit can have a zero or one depending on the input bits. 3758 3759.. code-block:: llvm 3760 3761 %A = or %X, undef 3762 %B = and %X, undef 3763 Safe: 3764 %A = -1 3765 %B = 0 3766 Safe: 3767 %A = %X ;; By choosing undef as 0 3768 %B = %X ;; By choosing undef as -1 3769 Unsafe: 3770 %A = undef 3771 %B = undef 3772 3773These logical operations have bits that are not always affected by the 3774input. For example, if ``%X`` has a zero bit, then the output of the 3775'``and``' operation will always be a zero for that bit, no matter what 3776the corresponding bit from the '``undef``' is. As such, it is unsafe to 3777optimize or assume that the result of the '``and``' is '``undef``'. 3778However, it is safe to assume that all bits of the '``undef``' could be 37790, and optimize the '``and``' to 0. Likewise, it is safe to assume that 3780all the bits of the '``undef``' operand to the '``or``' could be set, 3781allowing the '``or``' to be folded to -1. 3782 3783.. code-block:: llvm 3784 3785 %A = select undef, %X, %Y 3786 %B = select undef, 42, %Y 3787 %C = select %X, %Y, undef 3788 Safe: 3789 %A = %X (or %Y) 3790 %B = 42 (or %Y) 3791 %C = %Y 3792 Unsafe: 3793 %A = undef 3794 %B = undef 3795 %C = undef 3796 3797This set of examples shows that undefined '``select``' (and conditional 3798branch) conditions can go *either way*, but they have to come from one 3799of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were 3800both known to have a clear low bit, then ``%A`` would have to have a 3801cleared low bit. However, in the ``%C`` example, the optimizer is 3802allowed to assume that the '``undef``' operand could be the same as 3803``%Y``, allowing the whole '``select``' to be eliminated. 3804 3805.. code-block:: text 3806 3807 %A = xor undef, undef 3808 3809 %B = undef 3810 %C = xor %B, %B 3811 3812 %D = undef 3813 %E = icmp slt %D, 4 3814 %F = icmp gte %D, 4 3815 3816 Safe: 3817 %A = undef 3818 %B = undef 3819 %C = undef 3820 %D = undef 3821 %E = undef 3822 %F = undef 3823 3824This example points out that two '``undef``' operands are not 3825necessarily the same. This can be surprising to people (and also matches 3826C semantics) where they assume that "``X^X``" is always zero, even if 3827``X`` is undefined. This isn't true for a number of reasons, but the 3828short answer is that an '``undef``' "variable" can arbitrarily change 3829its value over its "live range". This is true because the variable 3830doesn't actually *have a live range*. Instead, the value is logically 3831read from arbitrary registers that happen to be around when needed, so 3832the value is not necessarily consistent over time. In fact, ``%A`` and 3833``%C`` need to have the same semantics or the core LLVM "replace all 3834uses with" concept would not hold. 3835 3836To ensure all uses of a given register observe the same value (even if 3837'``undef``'), the :ref:`freeze instruction <i_freeze>` can be used. 3838 3839.. code-block:: llvm 3840 3841 %A = sdiv undef, %X 3842 %B = sdiv %X, undef 3843 Safe: 3844 %A = 0 3845 b: unreachable 3846 3847These examples show the crucial difference between an *undefined value* 3848and *undefined behavior*. An undefined value (like '``undef``') is 3849allowed to have an arbitrary bit-pattern. This means that the ``%A`` 3850operation can be constant folded to '``0``', because the '``undef``' 3851could be zero, and zero divided by any value is zero. 3852However, in the second example, we can make a more aggressive 3853assumption: because the ``undef`` is allowed to be an arbitrary value, 3854we are allowed to assume that it could be zero. Since a divide by zero 3855has *undefined behavior*, we are allowed to assume that the operation 3856does not execute at all. This allows us to delete the divide and all 3857code after it. Because the undefined operation "can't happen", the 3858optimizer can assume that it occurs in dead code. 3859 3860.. code-block:: text 3861 3862 a: store undef -> %X 3863 b: store %X -> undef 3864 Safe: 3865 a: <deleted> 3866 b: unreachable 3867 3868A store *of* an undefined value can be assumed to not have any effect; 3869we can assume that the value is overwritten with bits that happen to 3870match what was already there. However, a store *to* an undefined 3871location could clobber arbitrary memory, therefore, it has undefined 3872behavior. 3873 3874Branching on an undefined value is undefined behavior. 3875This explains optimizations that depend on branch conditions to construct 3876predicates, such as Correlated Value Propagation and Global Value Numbering. 3877In case of switch instruction, the branch condition should be frozen, otherwise 3878it is undefined behavior. 3879 3880.. code-block:: text 3881 3882 Unsafe: 3883 br undef, BB1, BB2 ; UB 3884 3885 %X = and i32 undef, 255 3886 switch %X, label %ret [ .. ] ; UB 3887 3888 store undef, i8* %ptr 3889 %X = load i8* %ptr ; %X is undef 3890 switch i8 %X, label %ret [ .. ] ; UB 3891 3892 Safe: 3893 %X = or i8 undef, 255 ; always 255 3894 switch i8 %X, label %ret [ .. ] ; Well-defined 3895 3896 %X = freeze i1 undef 3897 br %X, BB1, BB2 ; Well-defined (non-deterministic jump) 3898 3899 3900This is also consistent with the behavior of MemorySanitizer. 3901MemorySanitizer, detector of uses of uninitialized memory, 3902defines a branch with condition that depends on an undef value (or 3903certain other values, like e.g. a result of a load from heap-allocated 3904memory that has never been stored to) to have an externally visible 3905side effect. For this reason functions with *sanitize_memory* 3906attribute are not allowed to produce such branches "out of thin 3907air". More strictly, an optimization that inserts a conditional branch 3908is only valid if in all executions where the branch condition has at 3909least one undefined bit, the same branch condition is evaluated in the 3910input IR as well. 3911 3912.. _poisonvalues: 3913 3914Poison Values 3915------------- 3916 3917A poison value is a result of an erroneous operation. 3918In order to facilitate speculative execution, many instructions do not 3919invoke immediate undefined behavior when provided with illegal operands, 3920and return a poison value instead. 3921The string '``poison``' can be used anywhere a constant is expected, and 3922operations such as :ref:`add <i_add>` with the ``nsw`` flag can produce 3923a poison value. 3924 3925Poison value behavior is defined in terms of value *dependence*: 3926 3927- Values other than :ref:`phi <i_phi>` nodes, :ref:`select <i_select>`, and 3928 :ref:`freeze <i_freeze>` instructions depend on their operands. 3929- :ref:`Phi <i_phi>` nodes depend on the operand corresponding to 3930 their dynamic predecessor basic block. 3931- :ref:`Select <i_select>` instructions depend on their condition operand and 3932 their selected operand. 3933- Function arguments depend on the corresponding actual argument values 3934 in the dynamic callers of their functions. 3935- :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>` 3936 instructions that dynamically transfer control back to them. 3937- :ref:`Invoke <i_invoke>` instructions depend on the 3938 :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing 3939 call instructions that dynamically transfer control back to them. 3940- Non-volatile loads and stores depend on the most recent stores to all 3941 of the referenced memory addresses, following the order in the IR 3942 (including loads and stores implied by intrinsics such as 3943 :ref:`@llvm.memcpy <int_memcpy>`.) 3944- An instruction with externally visible side effects depends on the 3945 most recent preceding instruction with externally visible side 3946 effects, following the order in the IR. (This includes :ref:`volatile 3947 operations <volatile>`.) 3948- An instruction *control-depends* on a :ref:`terminator 3949 instruction <terminators>` if the terminator instruction has 3950 multiple successors and the instruction is always executed when 3951 control transfers to one of the successors, and may not be executed 3952 when control is transferred to another. 3953- Additionally, an instruction also *control-depends* on a terminator 3954 instruction if the set of instructions it otherwise depends on would 3955 be different if the terminator had transferred control to a different 3956 successor. 3957- Dependence is transitive. 3958- Vector elements may be independently poisoned. Therefore, transforms 3959 on instructions such as shufflevector must be careful to propagate 3960 poison across values or elements only as allowed by the original code. 3961 3962An instruction that *depends* on a poison value, produces a poison value 3963itself. A poison value may be relaxed into an 3964:ref:`undef value <undefvalues>`, which takes an arbitrary bit-pattern. 3965Propagation of poison can be stopped with the 3966:ref:`freeze instruction <i_freeze>`. 3967 3968This means that immediate undefined behavior occurs if a poison value is 3969used as an instruction operand that has any values that trigger undefined 3970behavior. Notably this includes (but is not limited to): 3971 3972- The pointer operand of a :ref:`load <i_load>`, :ref:`store <i_store>` or 3973 any other pointer dereferencing instruction (independent of address 3974 space). 3975- The divisor operand of a ``udiv``, ``sdiv``, ``urem`` or ``srem`` 3976 instruction. 3977- The condition operand of a :ref:`br <i_br>` instruction. 3978- The callee operand of a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 3979 instruction. 3980- The parameter operand of a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 3981 instruction, when the function or invoking call site has a ``noundef`` 3982 attribute in the corresponding position. 3983- The operand of a :ref:`ret <i_ret>` instruction if the function or invoking 3984 call site has a `noundef` attribute in the return value position. 3985 3986Here are some examples: 3987 3988.. code-block:: llvm 3989 3990 entry: 3991 %poison = sub nuw i32 0, 1 ; Results in a poison value. 3992 %poison2 = sub i32 poison, 1 ; Also results in a poison value. 3993 %still_poison = and i32 %poison, 0 ; 0, but also poison. 3994 %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison 3995 store i32 0, i32* %poison_yet_again ; Undefined behavior due to 3996 ; store to poison. 3997 3998 store i32 %poison, i32* @g ; Poison value stored to memory. 3999 %poison3 = load i32, i32* @g ; Poison value loaded back from memory. 4000 4001 %narrowaddr = bitcast i32* @g to i16* 4002 %wideaddr = bitcast i32* @g to i64* 4003 %poison4 = load i16, i16* %narrowaddr ; Returns a poison value. 4004 %poison5 = load i64, i64* %wideaddr ; Returns a poison value. 4005 4006 %cmp = icmp slt i32 %poison, 0 ; Returns a poison value. 4007 br i1 %cmp, label %end, label %end ; undefined behavior 4008 4009 end: 4010 4011.. _welldefinedvalues: 4012 4013Well-Defined Values 4014------------------- 4015 4016Given a program execution, a value is *well defined* if the value does not 4017have an undef bit and is not poison in the execution. 4018An aggregate value or vector is well defined if its elements are well defined. 4019The padding of an aggregate isn't considered, since it isn't visible 4020without storing it into memory and loading it with a different type. 4021 4022A constant of a :ref:`single value <t_single_value>`, non-vector type is well 4023defined if it is neither '``undef``' constant nor '``poison``' constant. 4024The result of :ref:`freeze instruction <i_freeze>` is well defined regardless 4025of its operand. 4026 4027.. _blockaddress: 4028 4029Addresses of Basic Blocks 4030------------------------- 4031 4032``blockaddress(@function, %block)`` 4033 4034The '``blockaddress``' constant computes the address of the specified 4035basic block in the specified function, and always has an ``i8*`` type. 4036Taking the address of the entry block is illegal. 4037 4038This value only has defined behavior when used as an operand to the 4039':ref:`indirectbr <i_indirectbr>`' or ':ref:`callbr <i_callbr>`'instruction, or 4040for comparisons against null. Pointer equality tests between labels addresses 4041results in undefined behavior --- though, again, comparison against null is ok, 4042and no label is equal to the null pointer. This may be passed around as an 4043opaque pointer sized value as long as the bits are not inspected. This 4044allows ``ptrtoint`` and arithmetic to be performed on these values so 4045long as the original value is reconstituted before the ``indirectbr`` or 4046``callbr`` instruction. 4047 4048Finally, some targets may provide defined semantics when using the value 4049as the operand to an inline assembly, but that is target specific. 4050 4051.. _dso_local_equivalent: 4052 4053DSO Local Equivalent 4054-------------------- 4055 4056``dso_local_equivalent @func`` 4057 4058A '``dso_local_equivalent``' constant represents a function which is 4059functionally equivalent to a given function, but is always defined in the 4060current linkage unit. The resulting pointer has the same type as the underlying 4061function. The resulting pointer is permitted, but not required, to be different 4062from a pointer to the function, and it may have different values in different 4063translation units. 4064 4065The target function may not have ``extern_weak`` linkage. 4066 4067``dso_local_equivalent`` can be implemented as such: 4068 4069- If the function has local linkage, hidden visibility, or is 4070 ``dso_local``, ``dso_local_equivalent`` can be implemented as simply a pointer 4071 to the function. 4072- ``dso_local_equivalent`` can be implemented with a stub that tail-calls the 4073 function. Many targets support relocations that resolve at link time to either 4074 a function or a stub for it, depending on if the function is defined within the 4075 linkage unit; LLVM will use this when available. (This is commonly called a 4076 "PLT stub".) On other targets, the stub may need to be emitted explicitly. 4077 4078This can be used wherever a ``dso_local`` instance of a function is needed without 4079needing to explicitly make the original function ``dso_local``. An instance where 4080this can be used is for static offset calculations between a function and some other 4081``dso_local`` symbol. This is especially useful for the Relative VTables C++ ABI, 4082where dynamic relocations for function pointers in VTables can be replaced with 4083static relocations for offsets between the VTable and virtual functions which 4084may not be ``dso_local``. 4085 4086This is currently only supported for ELF binary formats. 4087 4088.. _constantexprs: 4089 4090Constant Expressions 4091-------------------- 4092 4093Constant expressions are used to allow expressions involving other 4094constants to be used as constants. Constant expressions may be of any 4095:ref:`first class <t_firstclass>` type and may involve any LLVM operation 4096that does not have side effects (e.g. load and call are not supported). 4097The following is the syntax for constant expressions: 4098 4099``trunc (CST to TYPE)`` 4100 Perform the :ref:`trunc operation <i_trunc>` on constants. 4101``zext (CST to TYPE)`` 4102 Perform the :ref:`zext operation <i_zext>` on constants. 4103``sext (CST to TYPE)`` 4104 Perform the :ref:`sext operation <i_sext>` on constants. 4105``fptrunc (CST to TYPE)`` 4106 Truncate a floating-point constant to another floating-point type. 4107 The size of CST must be larger than the size of TYPE. Both types 4108 must be floating-point. 4109``fpext (CST to TYPE)`` 4110 Floating-point extend a constant to another type. The size of CST 4111 must be smaller or equal to the size of TYPE. Both types must be 4112 floating-point. 4113``fptoui (CST to TYPE)`` 4114 Convert a floating-point constant to the corresponding unsigned 4115 integer constant. TYPE must be a scalar or vector integer type. CST 4116 must be of scalar or vector floating-point type. Both CST and TYPE 4117 must be scalars, or vectors of the same number of elements. If the 4118 value won't fit in the integer type, the result is a 4119 :ref:`poison value <poisonvalues>`. 4120``fptosi (CST to TYPE)`` 4121 Convert a floating-point constant to the corresponding signed 4122 integer constant. TYPE must be a scalar or vector integer type. CST 4123 must be of scalar or vector floating-point type. Both CST and TYPE 4124 must be scalars, or vectors of the same number of elements. If the 4125 value won't fit in the integer type, the result is a 4126 :ref:`poison value <poisonvalues>`. 4127``uitofp (CST to TYPE)`` 4128 Convert an unsigned integer constant to the corresponding 4129 floating-point constant. TYPE must be a scalar or vector floating-point 4130 type. CST must be of scalar or vector integer type. Both CST and TYPE must 4131 be scalars, or vectors of the same number of elements. 4132``sitofp (CST to TYPE)`` 4133 Convert a signed integer constant to the corresponding floating-point 4134 constant. TYPE must be a scalar or vector floating-point type. 4135 CST must be of scalar or vector integer type. Both CST and TYPE must 4136 be scalars, or vectors of the same number of elements. 4137``ptrtoint (CST to TYPE)`` 4138 Perform the :ref:`ptrtoint operation <i_ptrtoint>` on constants. 4139``inttoptr (CST to TYPE)`` 4140 Perform the :ref:`inttoptr operation <i_inttoptr>` on constants. 4141 This one is *really* dangerous! 4142``bitcast (CST to TYPE)`` 4143 Convert a constant, CST, to another TYPE. 4144 The constraints of the operands are the same as those for the 4145 :ref:`bitcast instruction <i_bitcast>`. 4146``addrspacecast (CST to TYPE)`` 4147 Convert a constant pointer or constant vector of pointer, CST, to another 4148 TYPE in a different address space. The constraints of the operands are the 4149 same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`. 4150``getelementptr (TY, CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (TY, CSTPTR, IDX0, IDX1, ...)`` 4151 Perform the :ref:`getelementptr operation <i_getelementptr>` on 4152 constants. As with the :ref:`getelementptr <i_getelementptr>` 4153 instruction, the index list may have one or more indexes, which are 4154 required to make sense for the type of "pointer to TY". 4155``select (COND, VAL1, VAL2)`` 4156 Perform the :ref:`select operation <i_select>` on constants. 4157``icmp COND (VAL1, VAL2)`` 4158 Perform the :ref:`icmp operation <i_icmp>` on constants. 4159``fcmp COND (VAL1, VAL2)`` 4160 Perform the :ref:`fcmp operation <i_fcmp>` on constants. 4161``extractelement (VAL, IDX)`` 4162 Perform the :ref:`extractelement operation <i_extractelement>` on 4163 constants. 4164``insertelement (VAL, ELT, IDX)`` 4165 Perform the :ref:`insertelement operation <i_insertelement>` on 4166 constants. 4167``shufflevector (VEC1, VEC2, IDXMASK)`` 4168 Perform the :ref:`shufflevector operation <i_shufflevector>` on 4169 constants. 4170``extractvalue (VAL, IDX0, IDX1, ...)`` 4171 Perform the :ref:`extractvalue operation <i_extractvalue>` on 4172 constants. The index list is interpreted in a similar manner as 4173 indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At 4174 least one index value must be specified. 4175``insertvalue (VAL, ELT, IDX0, IDX1, ...)`` 4176 Perform the :ref:`insertvalue operation <i_insertvalue>` on constants. 4177 The index list is interpreted in a similar manner as indices in a 4178 ':ref:`getelementptr <i_getelementptr>`' operation. At least one index 4179 value must be specified. 4180``OPCODE (LHS, RHS)`` 4181 Perform the specified operation of the LHS and RHS constants. OPCODE 4182 may be any of the :ref:`binary <binaryops>` or :ref:`bitwise 4183 binary <bitwiseops>` operations. The constraints on operands are 4184 the same as those for the corresponding instruction (e.g. no bitwise 4185 operations on floating-point values are allowed). 4186 4187Other Values 4188============ 4189 4190.. _inlineasmexprs: 4191 4192Inline Assembler Expressions 4193---------------------------- 4194 4195LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level 4196Inline Assembly <moduleasm>`) through the use of a special value. This value 4197represents the inline assembler as a template string (containing the 4198instructions to emit), a list of operand constraints (stored as a string), a 4199flag that indicates whether or not the inline asm expression has side effects, 4200and a flag indicating whether the function containing the asm needs to align its 4201stack conservatively. 4202 4203The template string supports argument substitution of the operands using "``$``" 4204followed by a number, to indicate substitution of the given register/memory 4205location, as specified by the constraint string. "``${NUM:MODIFIER}``" may also 4206be used, where ``MODIFIER`` is a target-specific annotation for how to print the 4207operand (See :ref:`inline-asm-modifiers`). 4208 4209A literal "``$``" may be included by using "``$$``" in the template. To include 4210other special characters into the output, the usual "``\XX``" escapes may be 4211used, just as in other strings. Note that after template substitution, the 4212resulting assembly string is parsed by LLVM's integrated assembler unless it is 4213disabled -- even when emitting a ``.s`` file -- and thus must contain assembly 4214syntax known to LLVM. 4215 4216LLVM also supports a few more substitutions useful for writing inline assembly: 4217 4218- ``${:uid}``: Expands to a decimal integer unique to this inline assembly blob. 4219 This substitution is useful when declaring a local label. Many standard 4220 compiler optimizations, such as inlining, may duplicate an inline asm blob. 4221 Adding a blob-unique identifier ensures that the two labels will not conflict 4222 during assembly. This is used to implement `GCC's %= special format 4223 string <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_. 4224- ``${:comment}``: Expands to the comment character of the current target's 4225 assembly dialect. This is usually ``#``, but many targets use other strings, 4226 such as ``;``, ``//``, or ``!``. 4227- ``${:private}``: Expands to the assembler private label prefix. Labels with 4228 this prefix will not appear in the symbol table of the assembled object. 4229 Typically the prefix is ``L``, but targets may use other strings. ``.L`` is 4230 relatively popular. 4231 4232LLVM's support for inline asm is modeled closely on the requirements of Clang's 4233GCC-compatible inline-asm support. Thus, the feature-set and the constraint and 4234modifier codes listed here are similar or identical to those in GCC's inline asm 4235support. However, to be clear, the syntax of the template and constraint strings 4236described here is *not* the same as the syntax accepted by GCC and Clang, and, 4237while most constraint letters are passed through as-is by Clang, some get 4238translated to other codes when converting from the C source to the LLVM 4239assembly. 4240 4241An example inline assembler expression is: 4242 4243.. code-block:: llvm 4244 4245 i32 (i32) asm "bswap $0", "=r,r" 4246 4247Inline assembler expressions may **only** be used as the callee operand 4248of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction. 4249Thus, typically we have: 4250 4251.. code-block:: llvm 4252 4253 %X = call i32 asm "bswap $0", "=r,r"(i32 %Y) 4254 4255Inline asms with side effects not visible in the constraint list must be 4256marked as having side effects. This is done through the use of the 4257'``sideeffect``' keyword, like so: 4258 4259.. code-block:: llvm 4260 4261 call void asm sideeffect "eieio", ""() 4262 4263In some cases inline asms will contain code that will not work unless 4264the stack is aligned in some way, such as calls or SSE instructions on 4265x86, yet will not contain code that does that alignment within the asm. 4266The compiler should make conservative assumptions about what the asm 4267might contain and should generate its usual stack alignment code in the 4268prologue if the '``alignstack``' keyword is present: 4269 4270.. code-block:: llvm 4271 4272 call void asm alignstack "eieio", ""() 4273 4274Inline asms also support using non-standard assembly dialects. The 4275assumed dialect is ATT. When the '``inteldialect``' keyword is present, 4276the inline asm is using the Intel dialect. Currently, ATT and Intel are 4277the only supported dialects. An example is: 4278 4279.. code-block:: llvm 4280 4281 call void asm inteldialect "eieio", ""() 4282 4283If multiple keywords appear the '``sideeffect``' keyword must come 4284first, the '``alignstack``' keyword second and the '``inteldialect``' 4285keyword last. 4286 4287Inline Asm Constraint String 4288^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4289 4290The constraint list is a comma-separated string, each element containing one or 4291more constraint codes. 4292 4293For each element in the constraint list an appropriate register or memory 4294operand will be chosen, and it will be made available to assembly template 4295string expansion as ``$0`` for the first constraint in the list, ``$1`` for the 4296second, etc. 4297 4298There are three different types of constraints, which are distinguished by a 4299prefix symbol in front of the constraint code: Output, Input, and Clobber. The 4300constraints must always be given in that order: outputs first, then inputs, then 4301clobbers. They cannot be intermingled. 4302 4303There are also three different categories of constraint codes: 4304 4305- Register constraint. This is either a register class, or a fixed physical 4306 register. This kind of constraint will allocate a register, and if necessary, 4307 bitcast the argument or result to the appropriate type. 4308- Memory constraint. This kind of constraint is for use with an instruction 4309 taking a memory operand. Different constraints allow for different addressing 4310 modes used by the target. 4311- Immediate value constraint. This kind of constraint is for an integer or other 4312 immediate value which can be rendered directly into an instruction. The 4313 various target-specific constraints allow the selection of a value in the 4314 proper range for the instruction you wish to use it with. 4315 4316Output constraints 4317"""""""""""""""""" 4318 4319Output constraints are specified by an "``=``" prefix (e.g. "``=r``"). This 4320indicates that the assembly will write to this operand, and the operand will 4321then be made available as a return value of the ``asm`` expression. Output 4322constraints do not consume an argument from the call instruction. (Except, see 4323below about indirect outputs). 4324 4325Normally, it is expected that no output locations are written to by the assembly 4326expression until *all* of the inputs have been read. As such, LLVM may assign 4327the same register to an output and an input. If this is not safe (e.g. if the 4328assembly contains two instructions, where the first writes to one output, and 4329the second reads an input and writes to a second output), then the "``&``" 4330modifier must be used (e.g. "``=&r``") to specify that the output is an 4331"early-clobber" output. Marking an output as "early-clobber" ensures that LLVM 4332will not use the same register for any inputs (other than an input tied to this 4333output). 4334 4335Input constraints 4336""""""""""""""""" 4337 4338Input constraints do not have a prefix -- just the constraint codes. Each input 4339constraint will consume one argument from the call instruction. It is not 4340permitted for the asm to write to any input register or memory location (unless 4341that input is tied to an output). Note also that multiple inputs may all be 4342assigned to the same register, if LLVM can determine that they necessarily all 4343contain the same value. 4344 4345Instead of providing a Constraint Code, input constraints may also "tie" 4346themselves to an output constraint, by providing an integer as the constraint 4347string. Tied inputs still consume an argument from the call instruction, and 4348take up a position in the asm template numbering as is usual -- they will simply 4349be constrained to always use the same register as the output they've been tied 4350to. For example, a constraint string of "``=r,0``" says to assign a register for 4351output, and use that register as an input as well (it being the 0'th 4352constraint). 4353 4354It is permitted to tie an input to an "early-clobber" output. In that case, no 4355*other* input may share the same register as the input tied to the early-clobber 4356(even when the other input has the same value). 4357 4358You may only tie an input to an output which has a register constraint, not a 4359memory constraint. Only a single input may be tied to an output. 4360 4361There is also an "interesting" feature which deserves a bit of explanation: if a 4362register class constraint allocates a register which is too small for the value 4363type operand provided as input, the input value will be split into multiple 4364registers, and all of them passed to the inline asm. 4365 4366However, this feature is often not as useful as you might think. 4367 4368Firstly, the registers are *not* guaranteed to be consecutive. So, on those 4369architectures that have instructions which operate on multiple consecutive 4370instructions, this is not an appropriate way to support them. (e.g. the 32-bit 4371SparcV8 has a 64-bit load, which instruction takes a single 32-bit register. The 4372hardware then loads into both the named register, and the next register. This 4373feature of inline asm would not be useful to support that.) 4374 4375A few of the targets provide a template string modifier allowing explicit access 4376to the second register of a two-register operand (e.g. MIPS ``L``, ``M``, and 4377``D``). On such an architecture, you can actually access the second allocated 4378register (yet, still, not any subsequent ones). But, in that case, you're still 4379probably better off simply splitting the value into two separate operands, for 4380clarity. (e.g. see the description of the ``A`` constraint on X86, which, 4381despite existing only for use with this feature, is not really a good idea to 4382use) 4383 4384Indirect inputs and outputs 4385""""""""""""""""""""""""""" 4386 4387Indirect output or input constraints can be specified by the "``*``" modifier 4388(which goes after the "``=``" in case of an output). This indicates that the asm 4389will write to or read from the contents of an *address* provided as an input 4390argument. (Note that in this way, indirect outputs act more like an *input* than 4391an output: just like an input, they consume an argument of the call expression, 4392rather than producing a return value. An indirect output constraint is an 4393"output" only in that the asm is expected to write to the contents of the input 4394memory location, instead of just read from it). 4395 4396This is most typically used for memory constraint, e.g. "``=*m``", to pass the 4397address of a variable as a value. 4398 4399It is also possible to use an indirect *register* constraint, but only on output 4400(e.g. "``=*r``"). This will cause LLVM to allocate a register for an output 4401value normally, and then, separately emit a store to the address provided as 4402input, after the provided inline asm. (It's not clear what value this 4403functionality provides, compared to writing the store explicitly after the asm 4404statement, and it can only produce worse code, since it bypasses many 4405optimization passes. I would recommend not using it.) 4406 4407 4408Clobber constraints 4409""""""""""""""""""" 4410 4411A clobber constraint is indicated by a "``~``" prefix. A clobber does not 4412consume an input operand, nor generate an output. Clobbers cannot use any of the 4413general constraint code letters -- they may use only explicit register 4414constraints, e.g. "``~{eax}``". The one exception is that a clobber string of 4415"``~{memory}``" indicates that the assembly writes to arbitrary undeclared 4416memory locations -- not only the memory pointed to by a declared indirect 4417output. 4418 4419Note that clobbering named registers that are also present in output 4420constraints is not legal. 4421 4422 4423Constraint Codes 4424"""""""""""""""" 4425After a potential prefix comes constraint code, or codes. 4426 4427A Constraint Code is either a single letter (e.g. "``r``"), a "``^``" character 4428followed by two letters (e.g. "``^wc``"), or "``{``" register-name "``}``" 4429(e.g. "``{eax}``"). 4430 4431The one and two letter constraint codes are typically chosen to be the same as 4432GCC's constraint codes. 4433 4434A single constraint may include one or more than constraint code in it, leaving 4435it up to LLVM to choose which one to use. This is included mainly for 4436compatibility with the translation of GCC inline asm coming from clang. 4437 4438There are two ways to specify alternatives, and either or both may be used in an 4439inline asm constraint list: 4440 44411) Append the codes to each other, making a constraint code set. E.g. "``im``" 4442 or "``{eax}m``". This means "choose any of the options in the set". The 4443 choice of constraint is made independently for each constraint in the 4444 constraint list. 4445 44462) Use "``|``" between constraint code sets, creating alternatives. Every 4447 constraint in the constraint list must have the same number of alternative 4448 sets. With this syntax, the same alternative in *all* of the items in the 4449 constraint list will be chosen together. 4450 4451Putting those together, you might have a two operand constraint string like 4452``"rm|r,ri|rm"``. This indicates that if operand 0 is ``r`` or ``m``, then 4453operand 1 may be one of ``r`` or ``i``. If operand 0 is ``r``, then operand 1 4454may be one of ``r`` or ``m``. But, operand 0 and 1 cannot both be of type m. 4455 4456However, the use of either of the alternatives features is *NOT* recommended, as 4457LLVM is not able to make an intelligent choice about which one to use. (At the 4458point it currently needs to choose, not enough information is available to do so 4459in a smart way.) Thus, it simply tries to make a choice that's most likely to 4460compile, not one that will be optimal performance. (e.g., given "``rm``", it'll 4461always choose to use memory, not registers). And, if given multiple registers, 4462or multiple register classes, it will simply choose the first one. (In fact, it 4463doesn't currently even ensure explicitly specified physical registers are 4464unique, so specifying multiple physical registers as alternatives, like 4465``{r11}{r12},{r11}{r12}``, will assign r11 to both operands, not at all what was 4466intended.) 4467 4468Supported Constraint Code List 4469"""""""""""""""""""""""""""""" 4470 4471The constraint codes are, in general, expected to behave the same way they do in 4472GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C 4473inline asm code which was supported by GCC. A mismatch in behavior between LLVM 4474and GCC likely indicates a bug in LLVM. 4475 4476Some constraint codes are typically supported by all targets: 4477 4478- ``r``: A register in the target's general purpose register class. 4479- ``m``: A memory address operand. It is target-specific what addressing modes 4480 are supported, typical examples are register, or register + register offset, 4481 or register + immediate offset (of some target-specific size). 4482- ``i``: An integer constant (of target-specific width). Allows either a simple 4483 immediate, or a relocatable value. 4484- ``n``: An integer constant -- *not* including relocatable values. 4485- ``s``: An integer constant, but allowing *only* relocatable values. 4486- ``X``: Allows an operand of any kind, no constraint whatsoever. Typically 4487 useful to pass a label for an asm branch or call. 4488 4489 .. FIXME: but that surely isn't actually okay to jump out of an asm 4490 block without telling llvm about the control transfer???) 4491 4492- ``{register-name}``: Requires exactly the named physical register. 4493 4494Other constraints are target-specific: 4495 4496AArch64: 4497 4498- ``z``: An immediate integer 0. Outputs ``WZR`` or ``XZR``, as appropriate. 4499- ``I``: An immediate integer valid for an ``ADD`` or ``SUB`` instruction, 4500 i.e. 0 to 4095 with optional shift by 12. 4501- ``J``: An immediate integer that, when negated, is valid for an ``ADD`` or 4502 ``SUB`` instruction, i.e. -1 to -4095 with optional left shift by 12. 4503- ``K``: An immediate integer that is valid for the 'bitmask immediate 32' of a 4504 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 32-bit register. 4505- ``L``: An immediate integer that is valid for the 'bitmask immediate 64' of a 4506 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 64-bit register. 4507- ``M``: An immediate integer for use with the ``MOV`` assembly alias on a 4508 32-bit register. This is a superset of ``K``: in addition to the bitmask 4509 immediate, also allows immediate integers which can be loaded with a single 4510 ``MOVZ`` or ``MOVL`` instruction. 4511- ``N``: An immediate integer for use with the ``MOV`` assembly alias on a 4512 64-bit register. This is a superset of ``L``. 4513- ``Q``: Memory address operand must be in a single register (no 4514 offsets). (However, LLVM currently does this for the ``m`` constraint as 4515 well.) 4516- ``r``: A 32 or 64-bit integer register (W* or X*). 4517- ``w``: A 32, 64, or 128-bit floating-point, SIMD or SVE vector register. 4518- ``x``: Like w, but restricted to registers 0 to 15 inclusive. 4519- ``y``: Like w, but restricted to SVE vector registers Z0 to Z7 inclusive. 4520- ``Upl``: One of the low eight SVE predicate registers (P0 to P7) 4521- ``Upa``: Any of the SVE predicate registers (P0 to P15) 4522 4523AMDGPU: 4524 4525- ``r``: A 32 or 64-bit integer register. 4526- ``[0-9]v``: The 32-bit VGPR register, number 0-9. 4527- ``[0-9]s``: The 32-bit SGPR register, number 0-9. 4528- ``[0-9]a``: The 32-bit AGPR register, number 0-9. 4529- ``I``: An integer inline constant in the range from -16 to 64. 4530- ``J``: A 16-bit signed integer constant. 4531- ``A``: An integer or a floating-point inline constant. 4532- ``B``: A 32-bit signed integer constant. 4533- ``C``: A 32-bit unsigned integer constant or an integer inline constant in the range from -16 to 64. 4534- ``DA``: A 64-bit constant that can be split into two "A" constants. 4535- ``DB``: A 64-bit constant that can be split into two "B" constants. 4536 4537All ARM modes: 4538 4539- ``Q``, ``Um``, ``Un``, ``Uq``, ``Us``, ``Ut``, ``Uv``, ``Uy``: Memory address 4540 operand. Treated the same as operand ``m``, at the moment. 4541- ``Te``: An even general-purpose 32-bit integer register: ``r0,r2,...,r12,r14`` 4542- ``To``: An odd general-purpose 32-bit integer register: ``r1,r3,...,r11`` 4543 4544ARM and ARM's Thumb2 mode: 4545 4546- ``j``: An immediate integer between 0 and 65535 (valid for ``MOVW``) 4547- ``I``: An immediate integer valid for a data-processing instruction. 4548- ``J``: An immediate integer between -4095 and 4095. 4549- ``K``: An immediate integer whose bitwise inverse is valid for a 4550 data-processing instruction. (Can be used with template modifier "``B``" to 4551 print the inverted value). 4552- ``L``: An immediate integer whose negation is valid for a data-processing 4553 instruction. (Can be used with template modifier "``n``" to print the negated 4554 value). 4555- ``M``: A power of two or an integer between 0 and 32. 4556- ``N``: Invalid immediate constraint. 4557- ``O``: Invalid immediate constraint. 4558- ``r``: A general-purpose 32-bit integer register (``r0-r15``). 4559- ``l``: In Thumb2 mode, low 32-bit GPR registers (``r0-r7``). In ARM mode, same 4560 as ``r``. 4561- ``h``: In Thumb2 mode, a high 32-bit GPR register (``r8-r15``). In ARM mode, 4562 invalid. 4563- ``w``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4564 ``s0-s31``, ``d0-d31``, or ``q0-q15``, respectively. 4565- ``t``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4566 ``s0-s31``, ``d0-d15``, or ``q0-q7``, respectively. 4567- ``x``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4568 ``s0-s15``, ``d0-d7``, or ``q0-q3``, respectively. 4569 4570ARM's Thumb1 mode: 4571 4572- ``I``: An immediate integer between 0 and 255. 4573- ``J``: An immediate integer between -255 and -1. 4574- ``K``: An immediate integer between 0 and 255, with optional left-shift by 4575 some amount. 4576- ``L``: An immediate integer between -7 and 7. 4577- ``M``: An immediate integer which is a multiple of 4 between 0 and 1020. 4578- ``N``: An immediate integer between 0 and 31. 4579- ``O``: An immediate integer which is a multiple of 4 between -508 and 508. 4580- ``r``: A low 32-bit GPR register (``r0-r7``). 4581- ``l``: A low 32-bit GPR register (``r0-r7``). 4582- ``h``: A high GPR register (``r0-r7``). 4583- ``w``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4584 ``s0-s31``, ``d0-d31``, or ``q0-q15``, respectively. 4585- ``t``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4586 ``s0-s31``, ``d0-d15``, or ``q0-q7``, respectively. 4587- ``x``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4588 ``s0-s15``, ``d0-d7``, or ``q0-q3``, respectively. 4589 4590 4591Hexagon: 4592 4593- ``o``, ``v``: A memory address operand, treated the same as constraint ``m``, 4594 at the moment. 4595- ``r``: A 32 or 64-bit register. 4596 4597MSP430: 4598 4599- ``r``: An 8 or 16-bit register. 4600 4601MIPS: 4602 4603- ``I``: An immediate signed 16-bit integer. 4604- ``J``: An immediate integer zero. 4605- ``K``: An immediate unsigned 16-bit integer. 4606- ``L``: An immediate 32-bit integer, where the lower 16 bits are 0. 4607- ``N``: An immediate integer between -65535 and -1. 4608- ``O``: An immediate signed 15-bit integer. 4609- ``P``: An immediate integer between 1 and 65535. 4610- ``m``: A memory address operand. In MIPS-SE mode, allows a base address 4611 register plus 16-bit immediate offset. In MIPS mode, just a base register. 4612- ``R``: A memory address operand. In MIPS-SE mode, allows a base address 4613 register plus a 9-bit signed offset. In MIPS mode, the same as constraint 4614 ``m``. 4615- ``ZC``: A memory address operand, suitable for use in a ``pref``, ``ll``, or 4616 ``sc`` instruction on the given subtarget (details vary). 4617- ``r``, ``d``, ``y``: A 32 or 64-bit GPR register. 4618- ``f``: A 32 or 64-bit FPU register (``F0-F31``), or a 128-bit MSA register 4619 (``W0-W31``). In the case of MSA registers, it is recommended to use the ``w`` 4620 argument modifier for compatibility with GCC. 4621- ``c``: A 32-bit or 64-bit GPR register suitable for indirect jump (always 4622 ``25``). 4623- ``l``: The ``lo`` register, 32 or 64-bit. 4624- ``x``: Invalid. 4625 4626NVPTX: 4627 4628- ``b``: A 1-bit integer register. 4629- ``c`` or ``h``: A 16-bit integer register. 4630- ``r``: A 32-bit integer register. 4631- ``l`` or ``N``: A 64-bit integer register. 4632- ``f``: A 32-bit float register. 4633- ``d``: A 64-bit float register. 4634 4635 4636PowerPC: 4637 4638- ``I``: An immediate signed 16-bit integer. 4639- ``J``: An immediate unsigned 16-bit integer, shifted left 16 bits. 4640- ``K``: An immediate unsigned 16-bit integer. 4641- ``L``: An immediate signed 16-bit integer, shifted left 16 bits. 4642- ``M``: An immediate integer greater than 31. 4643- ``N``: An immediate integer that is an exact power of 2. 4644- ``O``: The immediate integer constant 0. 4645- ``P``: An immediate integer constant whose negation is a signed 16-bit 4646 constant. 4647- ``es``, ``o``, ``Q``, ``Z``, ``Zy``: A memory address operand, currently 4648 treated the same as ``m``. 4649- ``r``: A 32 or 64-bit integer register. 4650- ``b``: A 32 or 64-bit integer register, excluding ``R0`` (that is: 4651 ``R1-R31``). 4652- ``f``: A 32 or 64-bit float register (``F0-F31``), 4653- ``v``: For ``4 x f32`` or ``4 x f64`` types, a 128-bit altivec vector 4654 register (``V0-V31``). 4655 4656- ``y``: Condition register (``CR0-CR7``). 4657- ``wc``: An individual CR bit in a CR register. 4658- ``wa``, ``wd``, ``wf``: Any 128-bit VSX vector register, from the full VSX 4659 register set (overlapping both the floating-point and vector register files). 4660- ``ws``: A 32 or 64-bit floating-point register, from the full VSX register 4661 set. 4662 4663RISC-V: 4664 4665- ``A``: An address operand (using a general-purpose register, without an 4666 offset). 4667- ``I``: A 12-bit signed integer immediate operand. 4668- ``J``: A zero integer immediate operand. 4669- ``K``: A 5-bit unsigned integer immediate operand. 4670- ``f``: A 32- or 64-bit floating-point register (requires F or D extension). 4671- ``r``: A 32- or 64-bit general-purpose register (depending on the platform 4672 ``XLEN``). 4673 4674Sparc: 4675 4676- ``I``: An immediate 13-bit signed integer. 4677- ``r``: A 32-bit integer register. 4678- ``f``: Any floating-point register on SparcV8, or a floating-point 4679 register in the "low" half of the registers on SparcV9. 4680- ``e``: Any floating-point register. (Same as ``f`` on SparcV8.) 4681 4682SystemZ: 4683 4684- ``I``: An immediate unsigned 8-bit integer. 4685- ``J``: An immediate unsigned 12-bit integer. 4686- ``K``: An immediate signed 16-bit integer. 4687- ``L``: An immediate signed 20-bit integer. 4688- ``M``: An immediate integer 0x7fffffff. 4689- ``Q``: A memory address operand with a base address and a 12-bit immediate 4690 unsigned displacement. 4691- ``R``: A memory address operand with a base address, a 12-bit immediate 4692 unsigned displacement, and an index register. 4693- ``S``: A memory address operand with a base address and a 20-bit immediate 4694 signed displacement. 4695- ``T``: A memory address operand with a base address, a 20-bit immediate 4696 signed displacement, and an index register. 4697- ``r`` or ``d``: A 32, 64, or 128-bit integer register. 4698- ``a``: A 32, 64, or 128-bit integer address register (excludes R0, which in an 4699 address context evaluates as zero). 4700- ``h``: A 32-bit value in the high part of a 64bit data register 4701 (LLVM-specific) 4702- ``f``: A 32, 64, or 128-bit floating-point register. 4703 4704X86: 4705 4706- ``I``: An immediate integer between 0 and 31. 4707- ``J``: An immediate integer between 0 and 64. 4708- ``K``: An immediate signed 8-bit integer. 4709- ``L``: An immediate integer, 0xff or 0xffff or (in 64-bit mode only) 4710 0xffffffff. 4711- ``M``: An immediate integer between 0 and 3. 4712- ``N``: An immediate unsigned 8-bit integer. 4713- ``O``: An immediate integer between 0 and 127. 4714- ``e``: An immediate 32-bit signed integer. 4715- ``Z``: An immediate 32-bit unsigned integer. 4716- ``o``, ``v``: Treated the same as ``m``, at the moment. 4717- ``q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit 4718 ``l`` integer register. On X86-32, this is the ``a``, ``b``, ``c``, and ``d`` 4719 registers, and on X86-64, it is all of the integer registers. 4720- ``Q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit 4721 ``h`` integer register. This is the ``a``, ``b``, ``c``, and ``d`` registers. 4722- ``r`` or ``l``: An 8, 16, 32, or 64-bit integer register. 4723- ``R``: An 8, 16, 32, or 64-bit "legacy" integer register -- one which has 4724 existed since i386, and can be accessed without the REX prefix. 4725- ``f``: A 32, 64, or 80-bit '387 FPU stack pseudo-register. 4726- ``y``: A 64-bit MMX register, if MMX is enabled. 4727- ``x``: If SSE is enabled: a 32 or 64-bit scalar operand, or 128-bit vector 4728 operand in a SSE register. If AVX is also enabled, can also be a 256-bit 4729 vector operand in an AVX register. If AVX-512 is also enabled, can also be a 4730 512-bit vector operand in an AVX512 register, Otherwise, an error. 4731- ``Y``: The same as ``x``, if *SSE2* is enabled, otherwise an error. 4732- ``A``: Special case: allocates EAX first, then EDX, for a single operand (in 4733 32-bit mode, a 64-bit integer operand will get split into two registers). It 4734 is not recommended to use this constraint, as in 64-bit mode, the 64-bit 4735 operand will get allocated only to RAX -- if two 32-bit operands are needed, 4736 you're better off splitting it yourself, before passing it to the asm 4737 statement. 4738 4739XCore: 4740 4741- ``r``: A 32-bit integer register. 4742 4743 4744.. _inline-asm-modifiers: 4745 4746Asm template argument modifiers 4747^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4748 4749In the asm template string, modifiers can be used on the operand reference, like 4750"``${0:n}``". 4751 4752The modifiers are, in general, expected to behave the same way they do in 4753GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C 4754inline asm code which was supported by GCC. A mismatch in behavior between LLVM 4755and GCC likely indicates a bug in LLVM. 4756 4757Target-independent: 4758 4759- ``c``: Print an immediate integer constant unadorned, without 4760 the target-specific immediate punctuation (e.g. no ``$`` prefix). 4761- ``n``: Negate and print immediate integer constant unadorned, without the 4762 target-specific immediate punctuation (e.g. no ``$`` prefix). 4763- ``l``: Print as an unadorned label, without the target-specific label 4764 punctuation (e.g. no ``$`` prefix). 4765 4766AArch64: 4767 4768- ``w``: Print a GPR register with a ``w*`` name instead of ``x*`` name. E.g., 4769 instead of ``x30``, print ``w30``. 4770- ``x``: Print a GPR register with a ``x*`` name. (this is the default, anyhow). 4771- ``b``, ``h``, ``s``, ``d``, ``q``: Print a floating-point/SIMD register with a 4772 ``b*``, ``h*``, ``s*``, ``d*``, or ``q*`` name, rather than the default of 4773 ``v*``. 4774 4775AMDGPU: 4776 4777- ``r``: No effect. 4778 4779ARM: 4780 4781- ``a``: Print an operand as an address (with ``[`` and ``]`` surrounding a 4782 register). 4783- ``P``: No effect. 4784- ``q``: No effect. 4785- ``y``: Print a VFP single-precision register as an indexed double (e.g. print 4786 as ``d4[1]`` instead of ``s9``) 4787- ``B``: Bitwise invert and print an immediate integer constant without ``#`` 4788 prefix. 4789- ``L``: Print the low 16-bits of an immediate integer constant. 4790- ``M``: Print as a register set suitable for ldm/stm. Also prints *all* 4791 register operands subsequent to the specified one (!), so use carefully. 4792- ``Q``: Print the low-order register of a register-pair, or the low-order 4793 register of a two-register operand. 4794- ``R``: Print the high-order register of a register-pair, or the high-order 4795 register of a two-register operand. 4796- ``H``: Print the second register of a register-pair. (On a big-endian system, 4797 ``H`` is equivalent to ``Q``, and on little-endian system, ``H`` is equivalent 4798 to ``R``.) 4799 4800 .. FIXME: H doesn't currently support printing the second register 4801 of a two-register operand. 4802 4803- ``e``: Print the low doubleword register of a NEON quad register. 4804- ``f``: Print the high doubleword register of a NEON quad register. 4805- ``m``: Print the base register of a memory operand without the ``[`` and ``]`` 4806 adornment. 4807 4808Hexagon: 4809 4810- ``L``: Print the second register of a two-register operand. Requires that it 4811 has been allocated consecutively to the first. 4812 4813 .. FIXME: why is it restricted to consecutive ones? And there's 4814 nothing that ensures that happens, is there? 4815 4816- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise 4817 nothing. Used to print 'addi' vs 'add' instructions. 4818 4819MSP430: 4820 4821No additional modifiers. 4822 4823MIPS: 4824 4825- ``X``: Print an immediate integer as hexadecimal 4826- ``x``: Print the low 16 bits of an immediate integer as hexadecimal. 4827- ``d``: Print an immediate integer as decimal. 4828- ``m``: Subtract one and print an immediate integer as decimal. 4829- ``z``: Print $0 if an immediate zero, otherwise print normally. 4830- ``L``: Print the low-order register of a two-register operand, or prints the 4831 address of the low-order word of a double-word memory operand. 4832 4833 .. FIXME: L seems to be missing memory operand support. 4834 4835- ``M``: Print the high-order register of a two-register operand, or prints the 4836 address of the high-order word of a double-word memory operand. 4837 4838 .. FIXME: M seems to be missing memory operand support. 4839 4840- ``D``: Print the second register of a two-register operand, or prints the 4841 second word of a double-word memory operand. (On a big-endian system, ``D`` is 4842 equivalent to ``L``, and on little-endian system, ``D`` is equivalent to 4843 ``M``.) 4844- ``w``: No effect. Provided for compatibility with GCC which requires this 4845 modifier in order to print MSA registers (``W0-W31``) with the ``f`` 4846 constraint. 4847 4848NVPTX: 4849 4850- ``r``: No effect. 4851 4852PowerPC: 4853 4854- ``L``: Print the second register of a two-register operand. Requires that it 4855 has been allocated consecutively to the first. 4856 4857 .. FIXME: why is it restricted to consecutive ones? And there's 4858 nothing that ensures that happens, is there? 4859 4860- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise 4861 nothing. Used to print 'addi' vs 'add' instructions. 4862- ``y``: For a memory operand, prints formatter for a two-register X-form 4863 instruction. (Currently always prints ``r0,OPERAND``). 4864- ``U``: Prints 'u' if the memory operand is an update form, and nothing 4865 otherwise. (NOTE: LLVM does not support update form, so this will currently 4866 always print nothing) 4867- ``X``: Prints 'x' if the memory operand is an indexed form. (NOTE: LLVM does 4868 not support indexed form, so this will currently always print nothing) 4869 4870RISC-V: 4871 4872- ``i``: Print the letter 'i' if the operand is not a register, otherwise print 4873 nothing. Used to print 'addi' vs 'add' instructions, etc. 4874- ``z``: Print the register ``zero`` if an immediate zero, otherwise print 4875 normally. 4876 4877Sparc: 4878 4879- ``r``: No effect. 4880 4881SystemZ: 4882 4883SystemZ implements only ``n``, and does *not* support any of the other 4884target-independent modifiers. 4885 4886X86: 4887 4888- ``c``: Print an unadorned integer or symbol name. (The latter is 4889 target-specific behavior for this typically target-independent modifier). 4890- ``A``: Print a register name with a '``*``' before it. 4891- ``b``: Print an 8-bit register name (e.g. ``al``); do nothing on a memory 4892 operand. 4893- ``h``: Print the upper 8-bit register name (e.g. ``ah``); do nothing on a 4894 memory operand. 4895- ``w``: Print the 16-bit register name (e.g. ``ax``); do nothing on a memory 4896 operand. 4897- ``k``: Print the 32-bit register name (e.g. ``eax``); do nothing on a memory 4898 operand. 4899- ``q``: Print the 64-bit register name (e.g. ``rax``), if 64-bit registers are 4900 available, otherwise the 32-bit register name; do nothing on a memory operand. 4901- ``n``: Negate and print an unadorned integer, or, for operands other than an 4902 immediate integer (e.g. a relocatable symbol expression), print a '-' before 4903 the operand. (The behavior for relocatable symbol expressions is a 4904 target-specific behavior for this typically target-independent modifier) 4905- ``H``: Print a memory reference with additional offset +8. 4906- ``P``: Print a memory reference or operand for use as the argument of a call 4907 instruction. (E.g. omit ``(rip)``, even though it's PC-relative.) 4908 4909XCore: 4910 4911No additional modifiers. 4912 4913 4914Inline Asm Metadata 4915^^^^^^^^^^^^^^^^^^^ 4916 4917The call instructions that wrap inline asm nodes may have a 4918"``!srcloc``" MDNode attached to it that contains a list of constant 4919integers. If present, the code generator will use the integer as the 4920location cookie value when report errors through the ``LLVMContext`` 4921error reporting mechanisms. This allows a front-end to correlate backend 4922errors that occur with inline asm back to the source code that produced 4923it. For example: 4924 4925.. code-block:: llvm 4926 4927 call void asm sideeffect "something bad", ""(), !srcloc !42 4928 ... 4929 !42 = !{ i32 1234567 } 4930 4931It is up to the front-end to make sense of the magic numbers it places 4932in the IR. If the MDNode contains multiple constants, the code generator 4933will use the one that corresponds to the line of the asm that the error 4934occurs on. 4935 4936.. _metadata: 4937 4938Metadata 4939======== 4940 4941LLVM IR allows metadata to be attached to instructions in the program 4942that can convey extra information about the code to the optimizers and 4943code generator. One example application of metadata is source-level 4944debug information. There are two metadata primitives: strings and nodes. 4945 4946Metadata does not have a type, and is not a value. If referenced from a 4947``call`` instruction, it uses the ``metadata`` type. 4948 4949All metadata are identified in syntax by an exclamation point ('``!``'). 4950 4951.. _metadata-string: 4952 4953Metadata Nodes and Metadata Strings 4954----------------------------------- 4955 4956A metadata string is a string surrounded by double quotes. It can 4957contain any character by escaping non-printable characters with 4958"``\xx``" where "``xx``" is the two digit hex code. For example: 4959"``!"test\00"``". 4960 4961Metadata nodes are represented with notation similar to structure 4962constants (a comma separated list of elements, surrounded by braces and 4963preceded by an exclamation point). Metadata nodes can have any values as 4964their operand. For example: 4965 4966.. code-block:: llvm 4967 4968 !{ !"test\00", i32 10} 4969 4970Metadata nodes that aren't uniqued use the ``distinct`` keyword. For example: 4971 4972.. code-block:: text 4973 4974 !0 = distinct !{!"test\00", i32 10} 4975 4976``distinct`` nodes are useful when nodes shouldn't be merged based on their 4977content. They can also occur when transformations cause uniquing collisions 4978when metadata operands change. 4979 4980A :ref:`named metadata <namedmetadatastructure>` is a collection of 4981metadata nodes, which can be looked up in the module symbol table. For 4982example: 4983 4984.. code-block:: llvm 4985 4986 !foo = !{!4, !3} 4987 4988Metadata can be used as function arguments. Here the ``llvm.dbg.value`` 4989intrinsic is using three metadata arguments: 4990 4991.. code-block:: llvm 4992 4993 call void @llvm.dbg.value(metadata !24, metadata !25, metadata !26) 4994 4995Metadata can be attached to an instruction. Here metadata ``!21`` is attached 4996to the ``add`` instruction using the ``!dbg`` identifier: 4997 4998.. code-block:: llvm 4999 5000 %indvar.next = add i64 %indvar, 1, !dbg !21 5001 5002Metadata can also be attached to a function or a global variable. Here metadata 5003``!22`` is attached to the ``f1`` and ``f2`` functions, and the globals ``g1`` 5004and ``g2`` using the ``!dbg`` identifier: 5005 5006.. code-block:: llvm 5007 5008 declare !dbg !22 void @f1() 5009 define void @f2() !dbg !22 { 5010 ret void 5011 } 5012 5013 @g1 = global i32 0, !dbg !22 5014 @g2 = external global i32, !dbg !22 5015 5016A transformation is required to drop any metadata attachment that it does not 5017know or know it can't preserve. Currently there is an exception for metadata 5018attachment to globals for ``!type`` and ``!absolute_symbol`` which can't be 5019unconditionally dropped unless the global is itself deleted. 5020 5021Metadata attached to a module using named metadata may not be dropped, with 5022the exception of debug metadata (named metadata with the name ``!llvm.dbg.*``). 5023 5024More information about specific metadata nodes recognized by the 5025optimizers and code generator is found below. 5026 5027.. _specialized-metadata: 5028 5029Specialized Metadata Nodes 5030^^^^^^^^^^^^^^^^^^^^^^^^^^ 5031 5032Specialized metadata nodes are custom data structures in metadata (as opposed 5033to generic tuples). Their fields are labelled, and can be specified in any 5034order. 5035 5036These aren't inherently debug info centric, but currently all the specialized 5037metadata nodes are related to debug info. 5038 5039.. _DICompileUnit: 5040 5041DICompileUnit 5042""""""""""""" 5043 5044``DICompileUnit`` nodes represent a compile unit. The ``enums:``, 5045``retainedTypes:``, ``globals:``, ``imports:`` and ``macros:`` fields are tuples 5046containing the debug info to be emitted along with the compile unit, regardless 5047of code optimizations (some nodes are only emitted if there are references to 5048them from instructions). The ``debugInfoForProfiling:`` field is a boolean 5049indicating whether or not line-table discriminators are updated to provide 5050more-accurate debug info for profiling results. 5051 5052.. code-block:: text 5053 5054 !0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang", 5055 isOptimized: true, flags: "-O2", runtimeVersion: 2, 5056 splitDebugFilename: "abc.debug", emissionKind: FullDebug, 5057 enums: !2, retainedTypes: !3, globals: !4, imports: !5, 5058 macros: !6, dwoId: 0x0abcd) 5059 5060Compile unit descriptors provide the root scope for objects declared in a 5061specific compilation unit. File descriptors are defined using this scope. These 5062descriptors are collected by a named metadata node ``!llvm.dbg.cu``. They keep 5063track of global variables, type information, and imported entities (declarations 5064and namespaces). 5065 5066.. _DIFile: 5067 5068DIFile 5069"""""" 5070 5071``DIFile`` nodes represent files. The ``filename:`` can include slashes. 5072 5073.. code-block:: none 5074 5075 !0 = !DIFile(filename: "path/to/file", directory: "/path/to/dir", 5076 checksumkind: CSK_MD5, 5077 checksum: "000102030405060708090a0b0c0d0e0f") 5078 5079Files are sometimes used in ``scope:`` fields, and are the only valid target 5080for ``file:`` fields. 5081Valid values for ``checksumkind:`` field are: {CSK_None, CSK_MD5, CSK_SHA1, CSK_SHA256} 5082 5083.. _DIBasicType: 5084 5085DIBasicType 5086""""""""""" 5087 5088``DIBasicType`` nodes represent primitive types, such as ``int``, ``bool`` and 5089``float``. ``tag:`` defaults to ``DW_TAG_base_type``. 5090 5091.. code-block:: text 5092 5093 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8, 5094 encoding: DW_ATE_unsigned_char) 5095 !1 = !DIBasicType(tag: DW_TAG_unspecified_type, name: "decltype(nullptr)") 5096 5097The ``encoding:`` describes the details of the type. Usually it's one of the 5098following: 5099 5100.. code-block:: text 5101 5102 DW_ATE_address = 1 5103 DW_ATE_boolean = 2 5104 DW_ATE_float = 4 5105 DW_ATE_signed = 5 5106 DW_ATE_signed_char = 6 5107 DW_ATE_unsigned = 7 5108 DW_ATE_unsigned_char = 8 5109 5110.. _DISubroutineType: 5111 5112DISubroutineType 5113"""""""""""""""" 5114 5115``DISubroutineType`` nodes represent subroutine types. Their ``types:`` field 5116refers to a tuple; the first operand is the return type, while the rest are the 5117types of the formal arguments in order. If the first operand is ``null``, that 5118represents a function with no return value (such as ``void foo() {}`` in C++). 5119 5120.. code-block:: text 5121 5122 !0 = !BasicType(name: "int", size: 32, align: 32, DW_ATE_signed) 5123 !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char) 5124 !2 = !DISubroutineType(types: !{null, !0, !1}) ; void (int, char) 5125 5126.. _DIDerivedType: 5127 5128DIDerivedType 5129""""""""""""" 5130 5131``DIDerivedType`` nodes represent types derived from other types, such as 5132qualified types. 5133 5134.. code-block:: text 5135 5136 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8, 5137 encoding: DW_ATE_unsigned_char) 5138 !1 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !0, size: 32, 5139 align: 32) 5140 5141The following ``tag:`` values are valid: 5142 5143.. code-block:: text 5144 5145 DW_TAG_member = 13 5146 DW_TAG_pointer_type = 15 5147 DW_TAG_reference_type = 16 5148 DW_TAG_typedef = 22 5149 DW_TAG_inheritance = 28 5150 DW_TAG_ptr_to_member_type = 31 5151 DW_TAG_const_type = 38 5152 DW_TAG_friend = 42 5153 DW_TAG_volatile_type = 53 5154 DW_TAG_restrict_type = 55 5155 DW_TAG_atomic_type = 71 5156 5157.. _DIDerivedTypeMember: 5158 5159``DW_TAG_member`` is used to define a member of a :ref:`composite type 5160<DICompositeType>`. The type of the member is the ``baseType:``. The 5161``offset:`` is the member's bit offset. If the composite type has an ODR 5162``identifier:`` and does not set ``flags: DIFwdDecl``, then the member is 5163uniqued based only on its ``name:`` and ``scope:``. 5164 5165``DW_TAG_inheritance`` and ``DW_TAG_friend`` are used in the ``elements:`` 5166field of :ref:`composite types <DICompositeType>` to describe parents and 5167friends. 5168 5169``DW_TAG_typedef`` is used to provide a name for the ``baseType:``. 5170 5171``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``, 5172``DW_TAG_volatile_type``, ``DW_TAG_restrict_type`` and ``DW_TAG_atomic_type`` 5173are used to qualify the ``baseType:``. 5174 5175Note that the ``void *`` type is expressed as a type derived from NULL. 5176 5177.. _DICompositeType: 5178 5179DICompositeType 5180""""""""""""""" 5181 5182``DICompositeType`` nodes represent types composed of other types, like 5183structures and unions. ``elements:`` points to a tuple of the composed types. 5184 5185If the source language supports ODR, the ``identifier:`` field gives the unique 5186identifier used for type merging between modules. When specified, 5187:ref:`subprogram declarations <DISubprogramDeclaration>` and :ref:`member 5188derived types <DIDerivedTypeMember>` that reference the ODR-type in their 5189``scope:`` change uniquing rules. 5190 5191For a given ``identifier:``, there should only be a single composite type that 5192does not have ``flags: DIFlagFwdDecl`` set. LLVM tools that link modules 5193together will unique such definitions at parse time via the ``identifier:`` 5194field, even if the nodes are ``distinct``. 5195 5196.. code-block:: text 5197 5198 !0 = !DIEnumerator(name: "SixKind", value: 7) 5199 !1 = !DIEnumerator(name: "SevenKind", value: 7) 5200 !2 = !DIEnumerator(name: "NegEightKind", value: -8) 5201 !3 = !DICompositeType(tag: DW_TAG_enumeration_type, name: "Enum", file: !12, 5202 line: 2, size: 32, align: 32, identifier: "_M4Enum", 5203 elements: !{!0, !1, !2}) 5204 5205The following ``tag:`` values are valid: 5206 5207.. code-block:: text 5208 5209 DW_TAG_array_type = 1 5210 DW_TAG_class_type = 2 5211 DW_TAG_enumeration_type = 4 5212 DW_TAG_structure_type = 19 5213 DW_TAG_union_type = 23 5214 5215For ``DW_TAG_array_type``, the ``elements:`` should be :ref:`subrange 5216descriptors <DISubrange>`, each representing the range of subscripts at that 5217level of indexing. The ``DIFlagVector`` flag to ``flags:`` indicates that an 5218array type is a native packed vector. The optional ``dataLocation`` is a 5219DIExpression that describes how to get from an object's address to the actual 5220raw data, if they aren't equivalent. This is only supported for array types, 5221particularly to describe Fortran arrays, which have an array descriptor in 5222addition to the array data. Alternatively it can also be DIVariable which 5223has the address of the actual raw data. The Fortran language supports pointer 5224arrays which can be attached to actual arrays, this attachment between pointer 5225and pointee is called association. The optional ``associated`` is a 5226DIExpression that describes whether the pointer array is currently associated. 5227The optional ``allocated`` is a DIExpression that describes whether the 5228allocatable array is currently allocated. The optional ``rank`` is a 5229DIExpression that describes the rank (number of dimensions) of fortran assumed 5230rank array (rank is known at runtime). 5231 5232For ``DW_TAG_enumeration_type``, the ``elements:`` should be :ref:`enumerator 5233descriptors <DIEnumerator>`, each representing the definition of an enumeration 5234value for the set. All enumeration type descriptors are collected in the 5235``enums:`` field of the :ref:`compile unit <DICompileUnit>`. 5236 5237For ``DW_TAG_structure_type``, ``DW_TAG_class_type``, and 5238``DW_TAG_union_type``, the ``elements:`` should be :ref:`derived types 5239<DIDerivedType>` with ``tag: DW_TAG_member``, ``tag: DW_TAG_inheritance``, or 5240``tag: DW_TAG_friend``; or :ref:`subprograms <DISubprogram>` with 5241``isDefinition: false``. 5242 5243.. _DISubrange: 5244 5245DISubrange 5246"""""""""" 5247 5248``DISubrange`` nodes are the elements for ``DW_TAG_array_type`` variants of 5249:ref:`DICompositeType`. 5250 5251- ``count: -1`` indicates an empty array. 5252- ``count: !9`` describes the count with a :ref:`DILocalVariable`. 5253- ``count: !11`` describes the count with a :ref:`DIGlobalVariable`. 5254 5255.. code-block:: text 5256 5257 !0 = !DISubrange(count: 5, lowerBound: 0) ; array counting from 0 5258 !1 = !DISubrange(count: 5, lowerBound: 1) ; array counting from 1 5259 !2 = !DISubrange(count: -1) ; empty array. 5260 5261 ; Scopes used in rest of example 5262 !6 = !DIFile(filename: "vla.c", directory: "/path/to/file") 5263 !7 = distinct !DICompileUnit(language: DW_LANG_C99, file: !6) 5264 !8 = distinct !DISubprogram(name: "foo", scope: !7, file: !6, line: 5) 5265 5266 ; Use of local variable as count value 5267 !9 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed) 5268 !10 = !DILocalVariable(name: "count", scope: !8, file: !6, line: 42, type: !9) 5269 !11 = !DISubrange(count: !10, lowerBound: 0) 5270 5271 ; Use of global variable as count value 5272 !12 = !DIGlobalVariable(name: "count", scope: !8, file: !6, line: 22, type: !9) 5273 !13 = !DISubrange(count: !12, lowerBound: 0) 5274 5275.. _DIEnumerator: 5276 5277DIEnumerator 5278"""""""""""" 5279 5280``DIEnumerator`` nodes are the elements for ``DW_TAG_enumeration_type`` 5281variants of :ref:`DICompositeType`. 5282 5283.. code-block:: text 5284 5285 !0 = !DIEnumerator(name: "SixKind", value: 7) 5286 !1 = !DIEnumerator(name: "SevenKind", value: 7) 5287 !2 = !DIEnumerator(name: "NegEightKind", value: -8) 5288 5289DITemplateTypeParameter 5290""""""""""""""""""""""" 5291 5292``DITemplateTypeParameter`` nodes represent type parameters to generic source 5293language constructs. They are used (optionally) in :ref:`DICompositeType` and 5294:ref:`DISubprogram` ``templateParams:`` fields. 5295 5296.. code-block:: text 5297 5298 !0 = !DITemplateTypeParameter(name: "Ty", type: !1) 5299 5300DITemplateValueParameter 5301"""""""""""""""""""""""" 5302 5303``DITemplateValueParameter`` nodes represent value parameters to generic source 5304language constructs. ``tag:`` defaults to ``DW_TAG_template_value_parameter``, 5305but if specified can also be set to ``DW_TAG_GNU_template_template_param`` or 5306``DW_TAG_GNU_template_param_pack``. They are used (optionally) in 5307:ref:`DICompositeType` and :ref:`DISubprogram` ``templateParams:`` fields. 5308 5309.. code-block:: text 5310 5311 !0 = !DITemplateValueParameter(name: "Ty", type: !1, value: i32 7) 5312 5313DINamespace 5314""""""""""" 5315 5316``DINamespace`` nodes represent namespaces in the source language. 5317 5318.. code-block:: text 5319 5320 !0 = !DINamespace(name: "myawesomeproject", scope: !1, file: !2, line: 7) 5321 5322.. _DIGlobalVariable: 5323 5324DIGlobalVariable 5325"""""""""""""""" 5326 5327``DIGlobalVariable`` nodes represent global variables in the source language. 5328 5329.. code-block:: text 5330 5331 @foo = global i32, !dbg !0 5332 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression()) 5333 !1 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !2, 5334 file: !3, line: 7, type: !4, isLocal: true, 5335 isDefinition: false, declaration: !5) 5336 5337 5338DIGlobalVariableExpression 5339"""""""""""""""""""""""""" 5340 5341``DIGlobalVariableExpression`` nodes tie a :ref:`DIGlobalVariable` together 5342with a :ref:`DIExpression`. 5343 5344.. code-block:: text 5345 5346 @lower = global i32, !dbg !0 5347 @upper = global i32, !dbg !1 5348 !0 = !DIGlobalVariableExpression( 5349 var: !2, 5350 expr: !DIExpression(DW_OP_LLVM_fragment, 0, 32) 5351 ) 5352 !1 = !DIGlobalVariableExpression( 5353 var: !2, 5354 expr: !DIExpression(DW_OP_LLVM_fragment, 32, 32) 5355 ) 5356 !2 = !DIGlobalVariable(name: "split64", linkageName: "split64", scope: !3, 5357 file: !4, line: 8, type: !5, declaration: !6) 5358 5359All global variable expressions should be referenced by the `globals:` field of 5360a :ref:`compile unit <DICompileUnit>`. 5361 5362.. _DISubprogram: 5363 5364DISubprogram 5365"""""""""""" 5366 5367``DISubprogram`` nodes represent functions from the source language. A distinct 5368``DISubprogram`` may be attached to a function definition using ``!dbg`` 5369metadata. A unique ``DISubprogram`` may be attached to a function declaration 5370used for call site debug info. The ``retainedNodes:`` field is a list of 5371:ref:`variables <DILocalVariable>` and :ref:`labels <DILabel>` that must be 5372retained, even if their IR counterparts are optimized out of the IR. The 5373``type:`` field must point at an :ref:`DISubroutineType`. 5374 5375.. _DISubprogramDeclaration: 5376 5377When ``isDefinition: false``, subprograms describe a declaration in the type 5378tree as opposed to a definition of a function. If the scope is a composite 5379type with an ODR ``identifier:`` and that does not set ``flags: DIFwdDecl``, 5380then the subprogram declaration is uniqued based only on its ``linkageName:`` 5381and ``scope:``. 5382 5383.. code-block:: text 5384 5385 define void @_Z3foov() !dbg !0 { 5386 ... 5387 } 5388 5389 !0 = distinct !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1, 5390 file: !2, line: 7, type: !3, isLocal: true, 5391 isDefinition: true, scopeLine: 8, 5392 containingType: !4, 5393 virtuality: DW_VIRTUALITY_pure_virtual, 5394 virtualIndex: 10, flags: DIFlagPrototyped, 5395 isOptimized: true, unit: !5, templateParams: !6, 5396 declaration: !7, retainedNodes: !8, 5397 thrownTypes: !9) 5398 5399.. _DILexicalBlock: 5400 5401DILexicalBlock 5402"""""""""""""" 5403 5404``DILexicalBlock`` nodes describe nested blocks within a :ref:`subprogram 5405<DISubprogram>`. The line number and column numbers are used to distinguish 5406two lexical blocks at same depth. They are valid targets for ``scope:`` 5407fields. 5408 5409.. code-block:: text 5410 5411 !0 = distinct !DILexicalBlock(scope: !1, file: !2, line: 7, column: 35) 5412 5413Usually lexical blocks are ``distinct`` to prevent node merging based on 5414operands. 5415 5416.. _DILexicalBlockFile: 5417 5418DILexicalBlockFile 5419"""""""""""""""""" 5420 5421``DILexicalBlockFile`` nodes are used to discriminate between sections of a 5422:ref:`lexical block <DILexicalBlock>`. The ``file:`` field can be changed to 5423indicate textual inclusion, or the ``discriminator:`` field can be used to 5424discriminate between control flow within a single block in the source language. 5425 5426.. code-block:: text 5427 5428 !0 = !DILexicalBlock(scope: !3, file: !4, line: 7, column: 35) 5429 !1 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 0) 5430 !2 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 1) 5431 5432.. _DILocation: 5433 5434DILocation 5435"""""""""" 5436 5437``DILocation`` nodes represent source debug locations. The ``scope:`` field is 5438mandatory, and points at an :ref:`DILexicalBlockFile`, an 5439:ref:`DILexicalBlock`, or an :ref:`DISubprogram`. 5440 5441.. code-block:: text 5442 5443 !0 = !DILocation(line: 2900, column: 42, scope: !1, inlinedAt: !2) 5444 5445.. _DILocalVariable: 5446 5447DILocalVariable 5448""""""""""""""" 5449 5450``DILocalVariable`` nodes represent local variables in the source language. If 5451the ``arg:`` field is set to non-zero, then this variable is a subprogram 5452parameter, and it will be included in the ``variables:`` field of its 5453:ref:`DISubprogram`. 5454 5455.. code-block:: text 5456 5457 !0 = !DILocalVariable(name: "this", arg: 1, scope: !3, file: !2, line: 7, 5458 type: !3, flags: DIFlagArtificial) 5459 !1 = !DILocalVariable(name: "x", arg: 2, scope: !4, file: !2, line: 7, 5460 type: !3) 5461 !2 = !DILocalVariable(name: "y", scope: !5, file: !2, line: 7, type: !3) 5462 5463.. _DIExpression: 5464 5465DIExpression 5466"""""""""""" 5467 5468``DIExpression`` nodes represent expressions that are inspired by the DWARF 5469expression language. They are used in :ref:`debug intrinsics<dbg_intrinsics>` 5470(such as ``llvm.dbg.declare`` and ``llvm.dbg.value``) to describe how the 5471referenced LLVM variable relates to the source language variable. Debug 5472intrinsics are interpreted left-to-right: start by pushing the value/address 5473operand of the intrinsic onto a stack, then repeatedly push and evaluate 5474opcodes from the DIExpression until the final variable description is produced. 5475 5476The current supported opcode vocabulary is limited: 5477 5478- ``DW_OP_deref`` dereferences the top of the expression stack. 5479- ``DW_OP_plus`` pops the last two entries from the expression stack, adds 5480 them together and appends the result to the expression stack. 5481- ``DW_OP_minus`` pops the last two entries from the expression stack, subtracts 5482 the last entry from the second last entry and appends the result to the 5483 expression stack. 5484- ``DW_OP_plus_uconst, 93`` adds ``93`` to the working expression. 5485- ``DW_OP_LLVM_fragment, 16, 8`` specifies the offset and size (``16`` and ``8`` 5486 here, respectively) of the variable fragment from the working expression. Note 5487 that contrary to DW_OP_bit_piece, the offset is describing the location 5488 within the described source variable. 5489- ``DW_OP_LLVM_convert, 16, DW_ATE_signed`` specifies a bit size and encoding 5490 (``16`` and ``DW_ATE_signed`` here, respectively) to which the top of the 5491 expression stack is to be converted. Maps into a ``DW_OP_convert`` operation 5492 that references a base type constructed from the supplied values. 5493- ``DW_OP_LLVM_tag_offset, tag_offset`` specifies that a memory tag should be 5494 optionally applied to the pointer. The memory tag is derived from the 5495 given tag offset in an implementation-defined manner. 5496- ``DW_OP_swap`` swaps top two stack entries. 5497- ``DW_OP_xderef`` provides extended dereference mechanism. The entry at the top 5498 of the stack is treated as an address. The second stack entry is treated as an 5499 address space identifier. 5500- ``DW_OP_stack_value`` marks a constant value. 5501- ``DW_OP_LLVM_entry_value, N`` may only appear in MIR and at the 5502 beginning of a ``DIExpression``. In DWARF a ``DBG_VALUE`` 5503 instruction binding a ``DIExpression(DW_OP_LLVM_entry_value`` to a 5504 register is lowered to a ``DW_OP_entry_value [reg]``, pushing the 5505 value the register had upon function entry onto the stack. The next 5506 ``(N - 1)`` operations will be part of the ``DW_OP_entry_value`` 5507 block argument. For example, ``!DIExpression(DW_OP_LLVM_entry_value, 5508 1, DW_OP_plus_uconst, 123, DW_OP_stack_value)`` specifies an 5509 expression where the entry value of the debug value instruction's 5510 value/address operand is pushed to the stack, and is added 5511 with 123. Due to framework limitations ``N`` can currently only 5512 be 1. 5513 5514 The operation is introduced by the ``LiveDebugValues`` pass, which 5515 applies it only to function parameters that are unmodified 5516 throughout the function. Support is limited to simple register 5517 location descriptions, or as indirect locations (e.g., when a struct 5518 is passed-by-value to a callee via a pointer to a temporary copy 5519 made in the caller). The entry value op is also introduced by the 5520 ``AsmPrinter`` pass when a call site parameter value 5521 (``DW_AT_call_site_parameter_value``) is represented as entry value 5522 of the parameter. 5523- ``DW_OP_LLVM_arg, N`` is used in debug intrinsics that refer to more than one 5524 value, such as one that calculates the sum of two registers. This is always 5525 used in combination with an ordered list of values, such that 5526 ``DW_OP_LLVM_arg, N`` refers to the ``N``th element in that list. For 5527 example, ``!DIExpression(DW_OP_LLVM_arg, 0, DW_OP_LLVM_arg, 1, DW_OP_minus, 5528 DW_OP_stack_value)`` used with the list ``(%reg1, %reg2)`` would evaluate to 5529 ``%reg1 - reg2``. This list of values should be provided by the containing 5530 intrinsic/instruction. 5531- ``DW_OP_breg`` (or ``DW_OP_bregx``) represents a content on the provided 5532 signed offset of the specified register. The opcode is only generated by the 5533 ``AsmPrinter`` pass to describe call site parameter value which requires an 5534 expression over two registers. 5535- ``DW_OP_push_object_address`` pushes the address of the object which can then 5536 serve as a descriptor in subsequent calculation. This opcode can be used to 5537 calculate bounds of fortran allocatable array which has array descriptors. 5538- ``DW_OP_over`` duplicates the entry currently second in the stack at the top 5539 of the stack. This opcode can be used to calculate bounds of fortran assumed 5540 rank array which has rank known at run time and current dimension number is 5541 implicitly first element of the stack. 5542- ``DW_OP_LLVM_implicit_pointer`` It specifies the dereferenced value. It can 5543 be used to represent pointer variables which are optimized out but the value 5544 it points to is known. This operator is required as it is different than DWARF 5545 operator DW_OP_implicit_pointer in representation and specification (number 5546 and types of operands) and later can not be used as multiple level. 5547 5548.. code-block:: text 5549 5550 IR for "*ptr = 4;" 5551 -------------- 5552 call void @llvm.dbg.value(metadata i32 4, metadata !17, metadata !20) 5553 !17 = !DILocalVariable(name: "ptr1", scope: !12, file: !3, line: 5, 5554 type: !18) 5555 !18 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !19, size: 64) 5556 !19 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed) 5557 !20 = !DIExpression(DW_OP_LLVM_implicit_pointer)) 5558 5559 IR for "**ptr = 4;" 5560 -------------- 5561 call void @llvm.dbg.value(metadata i32 4, metadata !17, metadata !21) 5562 !17 = !DILocalVariable(name: "ptr1", scope: !12, file: !3, line: 5, 5563 type: !18) 5564 !18 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !19, size: 64) 5565 !19 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !20, size: 64) 5566 !20 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed) 5567 !21 = !DIExpression(DW_OP_LLVM_implicit_pointer, 5568 DW_OP_LLVM_implicit_pointer)) 5569 5570DWARF specifies three kinds of simple location descriptions: Register, memory, 5571and implicit location descriptions. Note that a location description is 5572defined over certain ranges of a program, i.e the location of a variable may 5573change over the course of the program. Register and memory location 5574descriptions describe the *concrete location* of a source variable (in the 5575sense that a debugger might modify its value), whereas *implicit locations* 5576describe merely the actual *value* of a source variable which might not exist 5577in registers or in memory (see ``DW_OP_stack_value``). 5578 5579A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect 5580value (the address) of a source variable. The first operand of the intrinsic 5581must be an address of some kind. A DIExpression attached to the intrinsic 5582refines this address to produce a concrete location for the source variable. 5583 5584A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable. 5585The first operand of the intrinsic may be a direct or indirect value. A 5586DIExpression attached to the intrinsic refines the first operand to produce a 5587direct value. For example, if the first operand is an indirect value, it may be 5588necessary to insert ``DW_OP_deref`` into the DIExpression in order to produce a 5589valid debug intrinsic. 5590 5591.. note:: 5592 5593 A DIExpression is interpreted in the same way regardless of which kind of 5594 debug intrinsic it's attached to. 5595 5596.. code-block:: text 5597 5598 !0 = !DIExpression(DW_OP_deref) 5599 !1 = !DIExpression(DW_OP_plus_uconst, 3) 5600 !1 = !DIExpression(DW_OP_constu, 3, DW_OP_plus) 5601 !2 = !DIExpression(DW_OP_bit_piece, 3, 7) 5602 !3 = !DIExpression(DW_OP_deref, DW_OP_constu, 3, DW_OP_plus, DW_OP_LLVM_fragment, 3, 7) 5603 !4 = !DIExpression(DW_OP_constu, 2, DW_OP_swap, DW_OP_xderef) 5604 !5 = !DIExpression(DW_OP_constu, 42, DW_OP_stack_value) 5605 5606DIArgList 5607"""""""""""" 5608 5609``DIArgList`` nodes hold a list of constant or SSA value references. These are 5610used in :ref:`debug intrinsics<dbg_intrinsics>` (currently only in 5611``llvm.dbg.value``) in combination with a ``DIExpression`` that uses the 5612``DW_OP_LLVM_arg`` operator. Because a DIArgList may refer to local values 5613within a function, it must only be used as a function argument, must always be 5614inlined, and cannot appear in named metadata. 5615 5616.. code-block:: text 5617 5618 llvm.dbg.value(metadata !DIArgList(i32 %a, i32 %b), 5619 metadata !16, 5620 metadata !DIExpression(DW_OP_LLVM_arg, 0, DW_OP_LLVM_arg, 1, DW_OP_plus)) 5621 5622DIFlags 5623""""""""""""""" 5624 5625These flags encode various properties of DINodes. 5626 5627The `ExportSymbols` flag marks a class, struct or union whose members 5628may be referenced as if they were defined in the containing class or 5629union. This flag is used to decide whether the DW_AT_export_symbols can 5630be used for the structure type. 5631 5632DIObjCProperty 5633"""""""""""""" 5634 5635``DIObjCProperty`` nodes represent Objective-C property nodes. 5636 5637.. code-block:: text 5638 5639 !3 = !DIObjCProperty(name: "foo", file: !1, line: 7, setter: "setFoo", 5640 getter: "getFoo", attributes: 7, type: !2) 5641 5642DIImportedEntity 5643"""""""""""""""" 5644 5645``DIImportedEntity`` nodes represent entities (such as modules) imported into a 5646compile unit. 5647 5648.. code-block:: text 5649 5650 !2 = !DIImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0, 5651 entity: !1, line: 7) 5652 5653DIMacro 5654""""""" 5655 5656``DIMacro`` nodes represent definition or undefinition of a macro identifiers. 5657The ``name:`` field is the macro identifier, followed by macro parameters when 5658defining a function-like macro, and the ``value`` field is the token-string 5659used to expand the macro identifier. 5660 5661.. code-block:: text 5662 5663 !2 = !DIMacro(macinfo: DW_MACINFO_define, line: 7, name: "foo(x)", 5664 value: "((x) + 1)") 5665 !3 = !DIMacro(macinfo: DW_MACINFO_undef, line: 30, name: "foo") 5666 5667DIMacroFile 5668""""""""""" 5669 5670``DIMacroFile`` nodes represent inclusion of source files. 5671The ``nodes:`` field is a list of ``DIMacro`` and ``DIMacroFile`` nodes that 5672appear in the included source file. 5673 5674.. code-block:: text 5675 5676 !2 = !DIMacroFile(macinfo: DW_MACINFO_start_file, line: 7, file: !2, 5677 nodes: !3) 5678 5679.. _DILabel: 5680 5681DILabel 5682""""""" 5683 5684``DILabel`` nodes represent labels within a :ref:`DISubprogram`. All fields of 5685a ``DILabel`` are mandatory. The ``scope:`` field must be one of either a 5686:ref:`DILexicalBlockFile`, a :ref:`DILexicalBlock`, or a :ref:`DISubprogram`. 5687The ``name:`` field is the label identifier. The ``file:`` field is the 5688:ref:`DIFile` the label is present in. The ``line:`` field is the source line 5689within the file where the label is declared. 5690 5691.. code-block:: text 5692 5693 !2 = !DILabel(scope: !0, name: "foo", file: !1, line: 7) 5694 5695'``tbaa``' Metadata 5696^^^^^^^^^^^^^^^^^^^ 5697 5698In LLVM IR, memory does not have types, so LLVM's own type system is not 5699suitable for doing type based alias analysis (TBAA). Instead, metadata is 5700added to the IR to describe a type system of a higher level language. This 5701can be used to implement C/C++ strict type aliasing rules, but it can also 5702be used to implement custom alias analysis behavior for other languages. 5703 5704This description of LLVM's TBAA system is broken into two parts: 5705:ref:`Semantics<tbaa_node_semantics>` talks about high level issues, and 5706:ref:`Representation<tbaa_node_representation>` talks about the metadata 5707encoding of various entities. 5708 5709It is always possible to trace any TBAA node to a "root" TBAA node (details 5710in the :ref:`Representation<tbaa_node_representation>` section). TBAA 5711nodes with different roots have an unknown aliasing relationship, and LLVM 5712conservatively infers ``MayAlias`` between them. The rules mentioned in 5713this section only pertain to TBAA nodes living under the same root. 5714 5715.. _tbaa_node_semantics: 5716 5717Semantics 5718""""""""" 5719 5720The TBAA metadata system, referred to as "struct path TBAA" (not to be 5721confused with ``tbaa.struct``), consists of the following high level 5722concepts: *Type Descriptors*, further subdivided into scalar type 5723descriptors and struct type descriptors; and *Access Tags*. 5724 5725**Type descriptors** describe the type system of the higher level language 5726being compiled. **Scalar type descriptors** describe types that do not 5727contain other types. Each scalar type has a parent type, which must also 5728be a scalar type or the TBAA root. Via this parent relation, scalar types 5729within a TBAA root form a tree. **Struct type descriptors** denote types 5730that contain a sequence of other type descriptors, at known offsets. These 5731contained type descriptors can either be struct type descriptors themselves 5732or scalar type descriptors. 5733 5734**Access tags** are metadata nodes attached to load and store instructions. 5735Access tags use type descriptors to describe the *location* being accessed 5736in terms of the type system of the higher level language. Access tags are 5737tuples consisting of a base type, an access type and an offset. The base 5738type is a scalar type descriptor or a struct type descriptor, the access 5739type is a scalar type descriptor, and the offset is a constant integer. 5740 5741The access tag ``(BaseTy, AccessTy, Offset)`` can describe one of two 5742things: 5743 5744 * If ``BaseTy`` is a struct type, the tag describes a memory access (load 5745 or store) of a value of type ``AccessTy`` contained in the struct type 5746 ``BaseTy`` at offset ``Offset``. 5747 5748 * If ``BaseTy`` is a scalar type, ``Offset`` must be 0 and ``BaseTy`` and 5749 ``AccessTy`` must be the same; and the access tag describes a scalar 5750 access with scalar type ``AccessTy``. 5751 5752We first define an ``ImmediateParent`` relation on ``(BaseTy, Offset)`` 5753tuples this way: 5754 5755 * If ``BaseTy`` is a scalar type then ``ImmediateParent(BaseTy, 0)`` is 5756 ``(ParentTy, 0)`` where ``ParentTy`` is the parent of the scalar type as 5757 described in the TBAA metadata. ``ImmediateParent(BaseTy, Offset)`` is 5758 undefined if ``Offset`` is non-zero. 5759 5760 * If ``BaseTy`` is a struct type then ``ImmediateParent(BaseTy, Offset)`` 5761 is ``(NewTy, NewOffset)`` where ``NewTy`` is the type contained in 5762 ``BaseTy`` at offset ``Offset`` and ``NewOffset`` is ``Offset`` adjusted 5763 to be relative within that inner type. 5764 5765A memory access with an access tag ``(BaseTy1, AccessTy1, Offset1)`` 5766aliases a memory access with an access tag ``(BaseTy2, AccessTy2, 5767Offset2)`` if either ``(BaseTy1, Offset1)`` is reachable from ``(Base2, 5768Offset2)`` via the ``Parent`` relation or vice versa. 5769 5770As a concrete example, the type descriptor graph for the following program 5771 5772.. code-block:: c 5773 5774 struct Inner { 5775 int i; // offset 0 5776 float f; // offset 4 5777 }; 5778 5779 struct Outer { 5780 float f; // offset 0 5781 double d; // offset 4 5782 struct Inner inner_a; // offset 12 5783 }; 5784 5785 void f(struct Outer* outer, struct Inner* inner, float* f, int* i, char* c) { 5786 outer->f = 0; // tag0: (OuterStructTy, FloatScalarTy, 0) 5787 outer->inner_a.i = 0; // tag1: (OuterStructTy, IntScalarTy, 12) 5788 outer->inner_a.f = 0.0; // tag2: (OuterStructTy, FloatScalarTy, 16) 5789 *f = 0.0; // tag3: (FloatScalarTy, FloatScalarTy, 0) 5790 } 5791 5792is (note that in C and C++, ``char`` can be used to access any arbitrary 5793type): 5794 5795.. code-block:: text 5796 5797 Root = "TBAA Root" 5798 CharScalarTy = ("char", Root, 0) 5799 FloatScalarTy = ("float", CharScalarTy, 0) 5800 DoubleScalarTy = ("double", CharScalarTy, 0) 5801 IntScalarTy = ("int", CharScalarTy, 0) 5802 InnerStructTy = {"Inner" (IntScalarTy, 0), (FloatScalarTy, 4)} 5803 OuterStructTy = {"Outer", (FloatScalarTy, 0), (DoubleScalarTy, 4), 5804 (InnerStructTy, 12)} 5805 5806 5807with (e.g.) ``ImmediateParent(OuterStructTy, 12)`` = ``(InnerStructTy, 58080)``, ``ImmediateParent(InnerStructTy, 0)`` = ``(IntScalarTy, 0)``, and 5809``ImmediateParent(IntScalarTy, 0)`` = ``(CharScalarTy, 0)``. 5810 5811.. _tbaa_node_representation: 5812 5813Representation 5814"""""""""""""" 5815 5816The root node of a TBAA type hierarchy is an ``MDNode`` with 0 operands or 5817with exactly one ``MDString`` operand. 5818 5819Scalar type descriptors are represented as an ``MDNode`` s with two 5820operands. The first operand is an ``MDString`` denoting the name of the 5821struct type. LLVM does not assign meaning to the value of this operand, it 5822only cares about it being an ``MDString``. The second operand is an 5823``MDNode`` which points to the parent for said scalar type descriptor, 5824which is either another scalar type descriptor or the TBAA root. Scalar 5825type descriptors can have an optional third argument, but that must be the 5826constant integer zero. 5827 5828Struct type descriptors are represented as ``MDNode`` s with an odd number 5829of operands greater than 1. The first operand is an ``MDString`` denoting 5830the name of the struct type. Like in scalar type descriptors the actual 5831value of this name operand is irrelevant to LLVM. After the name operand, 5832the struct type descriptors have a sequence of alternating ``MDNode`` and 5833``ConstantInt`` operands. With N starting from 1, the 2N - 1 th operand, 5834an ``MDNode``, denotes a contained field, and the 2N th operand, a 5835``ConstantInt``, is the offset of the said contained field. The offsets 5836must be in non-decreasing order. 5837 5838Access tags are represented as ``MDNode`` s with either 3 or 4 operands. 5839The first operand is an ``MDNode`` pointing to the node representing the 5840base type. The second operand is an ``MDNode`` pointing to the node 5841representing the access type. The third operand is a ``ConstantInt`` that 5842states the offset of the access. If a fourth field is present, it must be 5843a ``ConstantInt`` valued at 0 or 1. If it is 1 then the access tag states 5844that the location being accessed is "constant" (meaning 5845``pointsToConstantMemory`` should return true; see `other useful 5846AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_). The TBAA root of 5847the access type and the base type of an access tag must be the same, and 5848that is the TBAA root of the access tag. 5849 5850'``tbaa.struct``' Metadata 5851^^^^^^^^^^^^^^^^^^^^^^^^^^ 5852 5853The :ref:`llvm.memcpy <int_memcpy>` is often used to implement 5854aggregate assignment operations in C and similar languages, however it 5855is defined to copy a contiguous region of memory, which is more than 5856strictly necessary for aggregate types which contain holes due to 5857padding. Also, it doesn't contain any TBAA information about the fields 5858of the aggregate. 5859 5860``!tbaa.struct`` metadata can describe which memory subregions in a 5861memcpy are padding and what the TBAA tags of the struct are. 5862 5863The current metadata format is very simple. ``!tbaa.struct`` metadata 5864nodes are a list of operands which are in conceptual groups of three. 5865For each group of three, the first operand gives the byte offset of a 5866field in bytes, the second gives its size in bytes, and the third gives 5867its tbaa tag. e.g.: 5868 5869.. code-block:: llvm 5870 5871 !4 = !{ i64 0, i64 4, !1, i64 8, i64 4, !2 } 5872 5873This describes a struct with two fields. The first is at offset 0 bytes 5874with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes 5875and has size 4 bytes and has tbaa tag !2. 5876 5877Note that the fields need not be contiguous. In this example, there is a 58784 byte gap between the two fields. This gap represents padding which 5879does not carry useful data and need not be preserved. 5880 5881'``noalias``' and '``alias.scope``' Metadata 5882^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5883 5884``noalias`` and ``alias.scope`` metadata provide the ability to specify generic 5885noalias memory-access sets. This means that some collection of memory access 5886instructions (loads, stores, memory-accessing calls, etc.) that carry 5887``noalias`` metadata can specifically be specified not to alias with some other 5888collection of memory access instructions that carry ``alias.scope`` metadata. 5889Each type of metadata specifies a list of scopes where each scope has an id and 5890a domain. 5891 5892When evaluating an aliasing query, if for some domain, the set 5893of scopes with that domain in one instruction's ``alias.scope`` list is a 5894subset of (or equal to) the set of scopes for that domain in another 5895instruction's ``noalias`` list, then the two memory accesses are assumed not to 5896alias. 5897 5898Because scopes in one domain don't affect scopes in other domains, separate 5899domains can be used to compose multiple independent noalias sets. This is 5900used for example during inlining. As the noalias function parameters are 5901turned into noalias scope metadata, a new domain is used every time the 5902function is inlined. 5903 5904The metadata identifying each domain is itself a list containing one or two 5905entries. The first entry is the name of the domain. Note that if the name is a 5906string then it can be combined across functions and translation units. A 5907self-reference can be used to create globally unique domain names. A 5908descriptive string may optionally be provided as a second list entry. 5909 5910The metadata identifying each scope is also itself a list containing two or 5911three entries. The first entry is the name of the scope. Note that if the name 5912is a string then it can be combined across functions and translation units. A 5913self-reference can be used to create globally unique scope names. A metadata 5914reference to the scope's domain is the second entry. A descriptive string may 5915optionally be provided as a third list entry. 5916 5917For example, 5918 5919.. code-block:: llvm 5920 5921 ; Two scope domains: 5922 !0 = !{!0} 5923 !1 = !{!1} 5924 5925 ; Some scopes in these domains: 5926 !2 = !{!2, !0} 5927 !3 = !{!3, !0} 5928 !4 = !{!4, !1} 5929 5930 ; Some scope lists: 5931 !5 = !{!4} ; A list containing only scope !4 5932 !6 = !{!4, !3, !2} 5933 !7 = !{!3} 5934 5935 ; These two instructions don't alias: 5936 %0 = load float, float* %c, align 4, !alias.scope !5 5937 store float %0, float* %arrayidx.i, align 4, !noalias !5 5938 5939 ; These two instructions also don't alias (for domain !1, the set of scopes 5940 ; in the !alias.scope equals that in the !noalias list): 5941 %2 = load float, float* %c, align 4, !alias.scope !5 5942 store float %2, float* %arrayidx.i2, align 4, !noalias !6 5943 5944 ; These two instructions may alias (for domain !0, the set of scopes in 5945 ; the !noalias list is not a superset of, or equal to, the scopes in the 5946 ; !alias.scope list): 5947 %2 = load float, float* %c, align 4, !alias.scope !6 5948 store float %0, float* %arrayidx.i, align 4, !noalias !7 5949 5950'``fpmath``' Metadata 5951^^^^^^^^^^^^^^^^^^^^^ 5952 5953``fpmath`` metadata may be attached to any instruction of floating-point 5954type. It can be used to express the maximum acceptable error in the 5955result of that instruction, in ULPs, thus potentially allowing the 5956compiler to use a more efficient but less accurate method of computing 5957it. ULP is defined as follows: 5958 5959 If ``x`` is a real number that lies between two finite consecutive 5960 floating-point numbers ``a`` and ``b``, without being equal to one 5961 of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the 5962 distance between the two non-equal finite floating-point numbers 5963 nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``. 5964 5965The metadata node shall consist of a single positive float type number 5966representing the maximum relative error, for example: 5967 5968.. code-block:: llvm 5969 5970 !0 = !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs 5971 5972.. _range-metadata: 5973 5974'``range``' Metadata 5975^^^^^^^^^^^^^^^^^^^^ 5976 5977``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of 5978integer types. It expresses the possible ranges the loaded value or the value 5979returned by the called function at this call site is in. If the loaded or 5980returned value is not in the specified range, the behavior is undefined. The 5981ranges are represented with a flattened list of integers. The loaded value or 5982the value returned is known to be in the union of the ranges defined by each 5983consecutive pair. Each pair has the following properties: 5984 5985- The type must match the type loaded by the instruction. 5986- The pair ``a,b`` represents the range ``[a,b)``. 5987- Both ``a`` and ``b`` are constants. 5988- The range is allowed to wrap. 5989- The range should not represent the full or empty set. That is, 5990 ``a!=b``. 5991 5992In addition, the pairs must be in signed order of the lower bound and 5993they must be non-contiguous. 5994 5995Examples: 5996 5997.. code-block:: llvm 5998 5999 %a = load i8, i8* %x, align 1, !range !0 ; Can only be 0 or 1 6000 %b = load i8, i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1 6001 %c = call i8 @foo(), !range !2 ; Can only be 0, 1, 3, 4 or 5 6002 %d = invoke i8 @bar() to label %cont 6003 unwind label %lpad, !range !3 ; Can only be -2, -1, 3, 4 or 5 6004 ... 6005 !0 = !{ i8 0, i8 2 } 6006 !1 = !{ i8 255, i8 2 } 6007 !2 = !{ i8 0, i8 2, i8 3, i8 6 } 6008 !3 = !{ i8 -2, i8 0, i8 3, i8 6 } 6009 6010'``absolute_symbol``' Metadata 6011^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6012 6013``absolute_symbol`` metadata may be attached to a global variable 6014declaration. It marks the declaration as a reference to an absolute symbol, 6015which causes the backend to use absolute relocations for the symbol even 6016in position independent code, and expresses the possible ranges that the 6017global variable's *address* (not its value) is in, in the same format as 6018``range`` metadata, with the extension that the pair ``all-ones,all-ones`` 6019may be used to represent the full set. 6020 6021Example (assuming 64-bit pointers): 6022 6023.. code-block:: llvm 6024 6025 @a = external global i8, !absolute_symbol !0 ; Absolute symbol in range [0,256) 6026 @b = external global i8, !absolute_symbol !1 ; Absolute symbol in range [0,2^64) 6027 6028 ... 6029 !0 = !{ i64 0, i64 256 } 6030 !1 = !{ i64 -1, i64 -1 } 6031 6032'``callees``' Metadata 6033^^^^^^^^^^^^^^^^^^^^^^ 6034 6035``callees`` metadata may be attached to indirect call sites. If ``callees`` 6036metadata is attached to a call site, and any callee is not among the set of 6037functions provided by the metadata, the behavior is undefined. The intent of 6038this metadata is to facilitate optimizations such as indirect-call promotion. 6039For example, in the code below, the call instruction may only target the 6040``add`` or ``sub`` functions: 6041 6042.. code-block:: llvm 6043 6044 %result = call i64 %binop(i64 %x, i64 %y), !callees !0 6045 6046 ... 6047 !0 = !{i64 (i64, i64)* @add, i64 (i64, i64)* @sub} 6048 6049'``callback``' Metadata 6050^^^^^^^^^^^^^^^^^^^^^^^ 6051 6052``callback`` metadata may be attached to a function declaration, or definition. 6053(Call sites are excluded only due to the lack of a use case.) For ease of 6054exposition, we'll refer to the function annotated w/ metadata as a broker 6055function. The metadata describes how the arguments of a call to the broker are 6056in turn passed to the callback function specified by the metadata. Thus, the 6057``callback`` metadata provides a partial description of a call site inside the 6058broker function with regards to the arguments of a call to the broker. The only 6059semantic restriction on the broker function itself is that it is not allowed to 6060inspect or modify arguments referenced in the ``callback`` metadata as 6061pass-through to the callback function. 6062 6063The broker is not required to actually invoke the callback function at runtime. 6064However, the assumptions about not inspecting or modifying arguments that would 6065be passed to the specified callback function still hold, even if the callback 6066function is not dynamically invoked. The broker is allowed to invoke the 6067callback function more than once per invocation of the broker. The broker is 6068also allowed to invoke (directly or indirectly) the function passed as a 6069callback through another use. Finally, the broker is also allowed to relay the 6070callback callee invocation to a different thread. 6071 6072The metadata is structured as follows: At the outer level, ``callback`` 6073metadata is a list of ``callback`` encodings. Each encoding starts with a 6074constant ``i64`` which describes the argument position of the callback function 6075in the call to the broker. The following elements, except the last, describe 6076what arguments are passed to the callback function. Each element is again an 6077``i64`` constant identifying the argument of the broker that is passed through, 6078or ``i64 -1`` to indicate an unknown or inspected argument. The order in which 6079they are listed has to be the same in which they are passed to the callback 6080callee. The last element of the encoding is a boolean which specifies how 6081variadic arguments of the broker are handled. If it is true, all variadic 6082arguments of the broker are passed through to the callback function *after* the 6083arguments encoded explicitly before. 6084 6085In the code below, the ``pthread_create`` function is marked as a broker 6086through the ``!callback !1`` metadata. In the example, there is only one 6087callback encoding, namely ``!2``, associated with the broker. This encoding 6088identifies the callback function as the second argument of the broker (``i64 60892``) and the sole argument of the callback function as the third one of the 6090broker function (``i64 3``). 6091 6092.. FIXME why does the llvm-sphinx-docs builder give a highlighting 6093 error if the below is set to highlight as 'llvm', despite that we 6094 have misc.highlighting_failure set? 6095 6096.. code-block:: text 6097 6098 declare !callback !1 dso_local i32 @pthread_create(i64*, %union.pthread_attr_t*, i8* (i8*)*, i8*) 6099 6100 ... 6101 !2 = !{i64 2, i64 3, i1 false} 6102 !1 = !{!2} 6103 6104Another example is shown below. The callback callee is the second argument of 6105the ``__kmpc_fork_call`` function (``i64 2``). The callee is given two unknown 6106values (each identified by a ``i64 -1``) and afterwards all 6107variadic arguments that are passed to the ``__kmpc_fork_call`` call (due to the 6108final ``i1 true``). 6109 6110.. FIXME why does the llvm-sphinx-docs builder give a highlighting 6111 error if the below is set to highlight as 'llvm', despite that we 6112 have misc.highlighting_failure set? 6113 6114.. code-block:: text 6115 6116 declare !callback !0 dso_local void @__kmpc_fork_call(%struct.ident_t*, i32, void (i32*, i32*, ...)*, ...) 6117 6118 ... 6119 !1 = !{i64 2, i64 -1, i64 -1, i1 true} 6120 !0 = !{!1} 6121 6122 6123'``unpredictable``' Metadata 6124^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6125 6126``unpredictable`` metadata may be attached to any branch or switch 6127instruction. It can be used to express the unpredictability of control 6128flow. Similar to the llvm.expect intrinsic, it may be used to alter 6129optimizations related to compare and branch instructions. The metadata 6130is treated as a boolean value; if it exists, it signals that the branch 6131or switch that it is attached to is completely unpredictable. 6132 6133.. _md_dereferenceable: 6134 6135'``dereferenceable``' Metadata 6136^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6137 6138The existence of the ``!dereferenceable`` metadata on the instruction 6139tells the optimizer that the value loaded is known to be dereferenceable. 6140The number of bytes known to be dereferenceable is specified by the integer 6141value in the metadata node. This is analogous to the ''dereferenceable'' 6142attribute on parameters and return values. 6143 6144.. _md_dereferenceable_or_null: 6145 6146'``dereferenceable_or_null``' Metadata 6147^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6148 6149The existence of the ``!dereferenceable_or_null`` metadata on the 6150instruction tells the optimizer that the value loaded is known to be either 6151dereferenceable or null. 6152The number of bytes known to be dereferenceable is specified by the integer 6153value in the metadata node. This is analogous to the ''dereferenceable_or_null'' 6154attribute on parameters and return values. 6155 6156.. _llvm.loop: 6157 6158'``llvm.loop``' 6159^^^^^^^^^^^^^^^ 6160 6161It is sometimes useful to attach information to loop constructs. Currently, 6162loop metadata is implemented as metadata attached to the branch instruction 6163in the loop latch block. The loop metadata node is a list of 6164other metadata nodes, each representing a property of the loop. Usually, 6165the first item of the property node is a string. For example, the 6166``llvm.loop.unroll.count`` suggests an unroll factor to the loop 6167unroller: 6168 6169.. code-block:: llvm 6170 6171 br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0 6172 ... 6173 !0 = !{!0, !1, !2} 6174 !1 = !{!"llvm.loop.unroll.enable"} 6175 !2 = !{!"llvm.loop.unroll.count", i32 4} 6176 6177For legacy reasons, the first item of a loop metadata node must be a 6178reference to itself. Before the advent of the 'distinct' keyword, this 6179forced the preservation of otherwise identical metadata nodes. Since 6180the loop-metadata node can be attached to multiple nodes, the 'distinct' 6181keyword has become unnecessary. 6182 6183Prior to the property nodes, one or two ``DILocation`` (debug location) 6184nodes can be present in the list. The first, if present, identifies the 6185source-code location where the loop begins. The second, if present, 6186identifies the source-code location where the loop ends. 6187 6188Loop metadata nodes cannot be used as unique identifiers. They are 6189neither persistent for the same loop through transformations nor 6190necessarily unique to just one loop. 6191 6192'``llvm.loop.disable_nonforced``' 6193^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6194 6195This metadata disables all optional loop transformations unless 6196explicitly instructed using other transformation metadata such as 6197``llvm.loop.unroll.enable``. That is, no heuristic will try to determine 6198whether a transformation is profitable. The purpose is to avoid that the 6199loop is transformed to a different loop before an explicitly requested 6200(forced) transformation is applied. For instance, loop fusion can make 6201other transformations impossible. Mandatory loop canonicalizations such 6202as loop rotation are still applied. 6203 6204It is recommended to use this metadata in addition to any llvm.loop.* 6205transformation directive. Also, any loop should have at most one 6206directive applied to it (and a sequence of transformations built using 6207followup-attributes). Otherwise, which transformation will be applied 6208depends on implementation details such as the pass pipeline order. 6209 6210See :ref:`transformation-metadata` for details. 6211 6212'``llvm.loop.vectorize``' and '``llvm.loop.interleave``' 6213^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6214 6215Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are 6216used to control per-loop vectorization and interleaving parameters such as 6217vectorization width and interleave count. These metadata should be used in 6218conjunction with ``llvm.loop`` loop identification metadata. The 6219``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only 6220optimization hints and the optimizer will only interleave and vectorize loops if 6221it believes it is safe to do so. The ``llvm.loop.parallel_accesses`` metadata 6222which contains information about loop-carried memory dependencies can be helpful 6223in determining the safety of these transformations. 6224 6225'``llvm.loop.interleave.count``' Metadata 6226^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6227 6228This metadata suggests an interleave count to the loop interleaver. 6229The first operand is the string ``llvm.loop.interleave.count`` and the 6230second operand is an integer specifying the interleave count. For 6231example: 6232 6233.. code-block:: llvm 6234 6235 !0 = !{!"llvm.loop.interleave.count", i32 4} 6236 6237Note that setting ``llvm.loop.interleave.count`` to 1 disables interleaving 6238multiple iterations of the loop. If ``llvm.loop.interleave.count`` is set to 0 6239then the interleave count will be determined automatically. 6240 6241'``llvm.loop.vectorize.enable``' Metadata 6242^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6243 6244This metadata selectively enables or disables vectorization for the loop. The 6245first operand is the string ``llvm.loop.vectorize.enable`` and the second operand 6246is a bit. If the bit operand value is 1 vectorization is enabled. A value of 62470 disables vectorization: 6248 6249.. code-block:: llvm 6250 6251 !0 = !{!"llvm.loop.vectorize.enable", i1 0} 6252 !1 = !{!"llvm.loop.vectorize.enable", i1 1} 6253 6254'``llvm.loop.vectorize.predicate.enable``' Metadata 6255^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6256 6257This metadata selectively enables or disables creating predicated instructions 6258for the loop, which can enable folding of the scalar epilogue loop into the 6259main loop. The first operand is the string 6260``llvm.loop.vectorize.predicate.enable`` and the second operand is a bit. If 6261the bit operand value is 1 vectorization is enabled. A value of 0 disables 6262vectorization: 6263 6264.. code-block:: llvm 6265 6266 !0 = !{!"llvm.loop.vectorize.predicate.enable", i1 0} 6267 !1 = !{!"llvm.loop.vectorize.predicate.enable", i1 1} 6268 6269'``llvm.loop.vectorize.scalable.enable``' Metadata 6270^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6271 6272This metadata selectively enables or disables scalable vectorization for the 6273loop, and only has any effect if vectorization for the loop is already enabled. 6274The first operand is the string ``llvm.loop.vectorize.scalable.enable`` 6275and the second operand is a bit. If the bit operand value is 1 scalable 6276vectorization is enabled, whereas a value of 0 reverts to the default fixed 6277width vectorization: 6278 6279.. code-block:: llvm 6280 6281 !0 = !{!"llvm.loop.vectorize.scalable.enable", i1 0} 6282 !1 = !{!"llvm.loop.vectorize.scalable.enable", i1 1} 6283 6284'``llvm.loop.vectorize.width``' Metadata 6285^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6286 6287This metadata sets the target width of the vectorizer. The first 6288operand is the string ``llvm.loop.vectorize.width`` and the second 6289operand is an integer specifying the width. For example: 6290 6291.. code-block:: llvm 6292 6293 !0 = !{!"llvm.loop.vectorize.width", i32 4} 6294 6295Note that setting ``llvm.loop.vectorize.width`` to 1 disables 6296vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to 62970 or if the loop does not have this metadata the width will be 6298determined automatically. 6299 6300'``llvm.loop.vectorize.followup_vectorized``' Metadata 6301^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6302 6303This metadata defines which loop attributes the vectorized loop will 6304have. See :ref:`transformation-metadata` for details. 6305 6306'``llvm.loop.vectorize.followup_epilogue``' Metadata 6307^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6308 6309This metadata defines which loop attributes the epilogue will have. The 6310epilogue is not vectorized and is executed when either the vectorized 6311loop is not known to preserve semantics (because e.g., it processes two 6312arrays that are found to alias by a runtime check) or for the last 6313iterations that do not fill a complete set of vector lanes. See 6314:ref:`Transformation Metadata <transformation-metadata>` for details. 6315 6316'``llvm.loop.vectorize.followup_all``' Metadata 6317^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6318 6319Attributes in the metadata will be added to both the vectorized and 6320epilogue loop. 6321See :ref:`Transformation Metadata <transformation-metadata>` for details. 6322 6323'``llvm.loop.unroll``' 6324^^^^^^^^^^^^^^^^^^^^^^ 6325 6326Metadata prefixed with ``llvm.loop.unroll`` are loop unrolling 6327optimization hints such as the unroll factor. ``llvm.loop.unroll`` 6328metadata should be used in conjunction with ``llvm.loop`` loop 6329identification metadata. The ``llvm.loop.unroll`` metadata are only 6330optimization hints and the unrolling will only be performed if the 6331optimizer believes it is safe to do so. 6332 6333'``llvm.loop.unroll.count``' Metadata 6334^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6335 6336This metadata suggests an unroll factor to the loop unroller. The 6337first operand is the string ``llvm.loop.unroll.count`` and the second 6338operand is a positive integer specifying the unroll factor. For 6339example: 6340 6341.. code-block:: llvm 6342 6343 !0 = !{!"llvm.loop.unroll.count", i32 4} 6344 6345If the trip count of the loop is less than the unroll count the loop 6346will be partially unrolled. 6347 6348'``llvm.loop.unroll.disable``' Metadata 6349^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6350 6351This metadata disables loop unrolling. The metadata has a single operand 6352which is the string ``llvm.loop.unroll.disable``. For example: 6353 6354.. code-block:: llvm 6355 6356 !0 = !{!"llvm.loop.unroll.disable"} 6357 6358'``llvm.loop.unroll.runtime.disable``' Metadata 6359^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6360 6361This metadata disables runtime loop unrolling. The metadata has a single 6362operand which is the string ``llvm.loop.unroll.runtime.disable``. For example: 6363 6364.. code-block:: llvm 6365 6366 !0 = !{!"llvm.loop.unroll.runtime.disable"} 6367 6368'``llvm.loop.unroll.enable``' Metadata 6369^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6370 6371This metadata suggests that the loop should be fully unrolled if the trip count 6372is known at compile time and partially unrolled if the trip count is not known 6373at compile time. The metadata has a single operand which is the string 6374``llvm.loop.unroll.enable``. For example: 6375 6376.. code-block:: llvm 6377 6378 !0 = !{!"llvm.loop.unroll.enable"} 6379 6380'``llvm.loop.unroll.full``' Metadata 6381^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6382 6383This metadata suggests that the loop should be unrolled fully. The 6384metadata has a single operand which is the string ``llvm.loop.unroll.full``. 6385For example: 6386 6387.. code-block:: llvm 6388 6389 !0 = !{!"llvm.loop.unroll.full"} 6390 6391'``llvm.loop.unroll.followup``' Metadata 6392^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6393 6394This metadata defines which loop attributes the unrolled loop will have. 6395See :ref:`Transformation Metadata <transformation-metadata>` for details. 6396 6397'``llvm.loop.unroll.followup_remainder``' Metadata 6398^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6399 6400This metadata defines which loop attributes the remainder loop after 6401partial/runtime unrolling will have. See 6402:ref:`Transformation Metadata <transformation-metadata>` for details. 6403 6404'``llvm.loop.unroll_and_jam``' 6405^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6406 6407This metadata is treated very similarly to the ``llvm.loop.unroll`` metadata 6408above, but affect the unroll and jam pass. In addition any loop with 6409``llvm.loop.unroll`` metadata but no ``llvm.loop.unroll_and_jam`` metadata will 6410disable unroll and jam (so ``llvm.loop.unroll`` metadata will be left to the 6411unroller, plus ``llvm.loop.unroll.disable`` metadata will disable unroll and jam 6412too.) 6413 6414The metadata for unroll and jam otherwise is the same as for ``unroll``. 6415``llvm.loop.unroll_and_jam.enable``, ``llvm.loop.unroll_and_jam.disable`` and 6416``llvm.loop.unroll_and_jam.count`` do the same as for unroll. 6417``llvm.loop.unroll_and_jam.full`` is not supported. Again these are only hints 6418and the normal safety checks will still be performed. 6419 6420'``llvm.loop.unroll_and_jam.count``' Metadata 6421^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6422 6423This metadata suggests an unroll and jam factor to use, similarly to 6424``llvm.loop.unroll.count``. The first operand is the string 6425``llvm.loop.unroll_and_jam.count`` and the second operand is a positive integer 6426specifying the unroll factor. For example: 6427 6428.. code-block:: llvm 6429 6430 !0 = !{!"llvm.loop.unroll_and_jam.count", i32 4} 6431 6432If the trip count of the loop is less than the unroll count the loop 6433will be partially unroll and jammed. 6434 6435'``llvm.loop.unroll_and_jam.disable``' Metadata 6436^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6437 6438This metadata disables loop unroll and jamming. The metadata has a single 6439operand which is the string ``llvm.loop.unroll_and_jam.disable``. For example: 6440 6441.. code-block:: llvm 6442 6443 !0 = !{!"llvm.loop.unroll_and_jam.disable"} 6444 6445'``llvm.loop.unroll_and_jam.enable``' Metadata 6446^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6447 6448This metadata suggests that the loop should be fully unroll and jammed if the 6449trip count is known at compile time and partially unrolled if the trip count is 6450not known at compile time. The metadata has a single operand which is the 6451string ``llvm.loop.unroll_and_jam.enable``. For example: 6452 6453.. code-block:: llvm 6454 6455 !0 = !{!"llvm.loop.unroll_and_jam.enable"} 6456 6457'``llvm.loop.unroll_and_jam.followup_outer``' Metadata 6458^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6459 6460This metadata defines which loop attributes the outer unrolled loop will 6461have. See :ref:`Transformation Metadata <transformation-metadata>` for 6462details. 6463 6464'``llvm.loop.unroll_and_jam.followup_inner``' Metadata 6465^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6466 6467This metadata defines which loop attributes the inner jammed loop will 6468have. See :ref:`Transformation Metadata <transformation-metadata>` for 6469details. 6470 6471'``llvm.loop.unroll_and_jam.followup_remainder_outer``' Metadata 6472^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6473 6474This metadata defines which attributes the epilogue of the outer loop 6475will have. This loop is usually unrolled, meaning there is no such 6476loop. This attribute will be ignored in this case. See 6477:ref:`Transformation Metadata <transformation-metadata>` for details. 6478 6479'``llvm.loop.unroll_and_jam.followup_remainder_inner``' Metadata 6480^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6481 6482This metadata defines which attributes the inner loop of the epilogue 6483will have. The outer epilogue will usually be unrolled, meaning there 6484can be multiple inner remainder loops. See 6485:ref:`Transformation Metadata <transformation-metadata>` for details. 6486 6487'``llvm.loop.unroll_and_jam.followup_all``' Metadata 6488^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6489 6490Attributes specified in the metadata is added to all 6491``llvm.loop.unroll_and_jam.*`` loops. See 6492:ref:`Transformation Metadata <transformation-metadata>` for details. 6493 6494'``llvm.loop.licm_versioning.disable``' Metadata 6495^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6496 6497This metadata indicates that the loop should not be versioned for the purpose 6498of enabling loop-invariant code motion (LICM). The metadata has a single operand 6499which is the string ``llvm.loop.licm_versioning.disable``. For example: 6500 6501.. code-block:: llvm 6502 6503 !0 = !{!"llvm.loop.licm_versioning.disable"} 6504 6505'``llvm.loop.distribute.enable``' Metadata 6506^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6507 6508Loop distribution allows splitting a loop into multiple loops. Currently, 6509this is only performed if the entire loop cannot be vectorized due to unsafe 6510memory dependencies. The transformation will attempt to isolate the unsafe 6511dependencies into their own loop. 6512 6513This metadata can be used to selectively enable or disable distribution of the 6514loop. The first operand is the string ``llvm.loop.distribute.enable`` and the 6515second operand is a bit. If the bit operand value is 1 distribution is 6516enabled. A value of 0 disables distribution: 6517 6518.. code-block:: llvm 6519 6520 !0 = !{!"llvm.loop.distribute.enable", i1 0} 6521 !1 = !{!"llvm.loop.distribute.enable", i1 1} 6522 6523This metadata should be used in conjunction with ``llvm.loop`` loop 6524identification metadata. 6525 6526'``llvm.loop.distribute.followup_coincident``' Metadata 6527^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6528 6529This metadata defines which attributes extracted loops with no cyclic 6530dependencies will have (i.e. can be vectorized). See 6531:ref:`Transformation Metadata <transformation-metadata>` for details. 6532 6533'``llvm.loop.distribute.followup_sequential``' Metadata 6534^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6535 6536This metadata defines which attributes the isolated loops with unsafe 6537memory dependencies will have. See 6538:ref:`Transformation Metadata <transformation-metadata>` for details. 6539 6540'``llvm.loop.distribute.followup_fallback``' Metadata 6541^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6542 6543If loop versioning is necessary, this metadata defined the attributes 6544the non-distributed fallback version will have. See 6545:ref:`Transformation Metadata <transformation-metadata>` for details. 6546 6547'``llvm.loop.distribute.followup_all``' Metadata 6548^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6549 6550The attributes in this metadata is added to all followup loops of the 6551loop distribution pass. See 6552:ref:`Transformation Metadata <transformation-metadata>` for details. 6553 6554'``llvm.licm.disable``' Metadata 6555^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6556 6557This metadata indicates that loop-invariant code motion (LICM) should not be 6558performed on this loop. The metadata has a single operand which is the string 6559``llvm.licm.disable``. For example: 6560 6561.. code-block:: llvm 6562 6563 !0 = !{!"llvm.licm.disable"} 6564 6565Note that although it operates per loop it isn't given the llvm.loop prefix 6566as it is not affected by the ``llvm.loop.disable_nonforced`` metadata. 6567 6568'``llvm.access.group``' Metadata 6569^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6570 6571``llvm.access.group`` metadata can be attached to any instruction that 6572potentially accesses memory. It can point to a single distinct metadata 6573node, which we call access group. This node represents all memory access 6574instructions referring to it via ``llvm.access.group``. When an 6575instruction belongs to multiple access groups, it can also point to a 6576list of accesses groups, illustrated by the following example. 6577 6578.. code-block:: llvm 6579 6580 %val = load i32, i32* %arrayidx, !llvm.access.group !0 6581 ... 6582 !0 = !{!1, !2} 6583 !1 = distinct !{} 6584 !2 = distinct !{} 6585 6586It is illegal for the list node to be empty since it might be confused 6587with an access group. 6588 6589The access group metadata node must be 'distinct' to avoid collapsing 6590multiple access groups by content. A access group metadata node must 6591always be empty which can be used to distinguish an access group 6592metadata node from a list of access groups. Being empty avoids the 6593situation that the content must be updated which, because metadata is 6594immutable by design, would required finding and updating all references 6595to the access group node. 6596 6597The access group can be used to refer to a memory access instruction 6598without pointing to it directly (which is not possible in global 6599metadata). Currently, the only metadata making use of it is 6600``llvm.loop.parallel_accesses``. 6601 6602'``llvm.loop.parallel_accesses``' Metadata 6603^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6604 6605The ``llvm.loop.parallel_accesses`` metadata refers to one or more 6606access group metadata nodes (see ``llvm.access.group``). It denotes that 6607no loop-carried memory dependence exist between it and other instructions 6608in the loop with this metadata. 6609 6610Let ``m1`` and ``m2`` be two instructions that both have the 6611``llvm.access.group`` metadata to the access group ``g1``, respectively 6612``g2`` (which might be identical). If a loop contains both access groups 6613in its ``llvm.loop.parallel_accesses`` metadata, then the compiler can 6614assume that there is no dependency between ``m1`` and ``m2`` carried by 6615this loop. Instructions that belong to multiple access groups are 6616considered having this property if at least one of the access groups 6617matches the ``llvm.loop.parallel_accesses`` list. 6618 6619If all memory-accessing instructions in a loop have 6620``llvm.access.group`` metadata that each refer to one of the access 6621groups of a loop's ``llvm.loop.parallel_accesses`` metadata, then the 6622loop has no loop carried memory dependences and is considered to be a 6623parallel loop. 6624 6625Note that if not all memory access instructions belong to an access 6626group referred to by ``llvm.loop.parallel_accesses``, then the loop must 6627not be considered trivially parallel. Additional 6628memory dependence analysis is required to make that determination. As a fail 6629safe mechanism, this causes loops that were originally parallel to be considered 6630sequential (if optimization passes that are unaware of the parallel semantics 6631insert new memory instructions into the loop body). 6632 6633Example of a loop that is considered parallel due to its correct use of 6634both ``llvm.access.group`` and ``llvm.loop.parallel_accesses`` 6635metadata types. 6636 6637.. code-block:: llvm 6638 6639 for.body: 6640 ... 6641 %val0 = load i32, i32* %arrayidx, !llvm.access.group !1 6642 ... 6643 store i32 %val0, i32* %arrayidx1, !llvm.access.group !1 6644 ... 6645 br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0 6646 6647 for.end: 6648 ... 6649 !0 = distinct !{!0, !{!"llvm.loop.parallel_accesses", !1}} 6650 !1 = distinct !{} 6651 6652It is also possible to have nested parallel loops: 6653 6654.. code-block:: llvm 6655 6656 outer.for.body: 6657 ... 6658 %val1 = load i32, i32* %arrayidx3, !llvm.access.group !4 6659 ... 6660 br label %inner.for.body 6661 6662 inner.for.body: 6663 ... 6664 %val0 = load i32, i32* %arrayidx1, !llvm.access.group !3 6665 ... 6666 store i32 %val0, i32* %arrayidx2, !llvm.access.group !3 6667 ... 6668 br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1 6669 6670 inner.for.end: 6671 ... 6672 store i32 %val1, i32* %arrayidx4, !llvm.access.group !4 6673 ... 6674 br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2 6675 6676 outer.for.end: ; preds = %for.body 6677 ... 6678 !1 = distinct !{!1, !{!"llvm.loop.parallel_accesses", !3}} ; metadata for the inner loop 6679 !2 = distinct !{!2, !{!"llvm.loop.parallel_accesses", !3, !4}} ; metadata for the outer loop 6680 !3 = distinct !{} ; access group for instructions in the inner loop (which are implicitly contained in outer loop as well) 6681 !4 = distinct !{} ; access group for instructions in the outer, but not the inner loop 6682 6683'``llvm.loop.mustprogress``' Metadata 6684^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6685 6686The ``llvm.loop.mustprogress`` metadata indicates that this loop is required to 6687terminate, unwind, or interact with the environment in an observable way e.g. 6688via a volatile memory access, I/O, or other synchronization. If such a loop is 6689not found to interact with the environment in an observable way, the loop may 6690be removed. This corresponds to the ``mustprogress`` function attribute. 6691 6692'``irr_loop``' Metadata 6693^^^^^^^^^^^^^^^^^^^^^^^ 6694 6695``irr_loop`` metadata may be attached to the terminator instruction of a basic 6696block that's an irreducible loop header (note that an irreducible loop has more 6697than once header basic blocks.) If ``irr_loop`` metadata is attached to the 6698terminator instruction of a basic block that is not really an irreducible loop 6699header, the behavior is undefined. The intent of this metadata is to improve the 6700accuracy of the block frequency propagation. For example, in the code below, the 6701block ``header0`` may have a loop header weight (relative to the other headers of 6702the irreducible loop) of 100: 6703 6704.. code-block:: llvm 6705 6706 header0: 6707 ... 6708 br i1 %cmp, label %t1, label %t2, !irr_loop !0 6709 6710 ... 6711 !0 = !{"loop_header_weight", i64 100} 6712 6713Irreducible loop header weights are typically based on profile data. 6714 6715.. _md_invariant.group: 6716 6717'``invariant.group``' Metadata 6718^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6719 6720The experimental ``invariant.group`` metadata may be attached to 6721``load``/``store`` instructions referencing a single metadata with no entries. 6722The existence of the ``invariant.group`` metadata on the instruction tells 6723the optimizer that every ``load`` and ``store`` to the same pointer operand 6724can be assumed to load or store the same 6725value (but see the ``llvm.launder.invariant.group`` intrinsic which affects 6726when two pointers are considered the same). Pointers returned by bitcast or 6727getelementptr with only zero indices are considered the same. 6728 6729Examples: 6730 6731.. code-block:: llvm 6732 6733 @unknownPtr = external global i8 6734 ... 6735 %ptr = alloca i8 6736 store i8 42, i8* %ptr, !invariant.group !0 6737 call void @foo(i8* %ptr) 6738 6739 %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change 6740 call void @foo(i8* %ptr) 6741 6742 %newPtr = call i8* @getPointer(i8* %ptr) 6743 %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr 6744 6745 %unknownValue = load i8, i8* @unknownPtr 6746 store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42 6747 6748 call void @foo(i8* %ptr) 6749 %newPtr2 = call i8* @llvm.launder.invariant.group(i8* %ptr) 6750 %d = load i8, i8* %newPtr2, !invariant.group !0 ; Can't step through launder.invariant.group to get value of %ptr 6751 6752 ... 6753 declare void @foo(i8*) 6754 declare i8* @getPointer(i8*) 6755 declare i8* @llvm.launder.invariant.group(i8*) 6756 6757 !0 = !{} 6758 6759The invariant.group metadata must be dropped when replacing one pointer by 6760another based on aliasing information. This is because invariant.group is tied 6761to the SSA value of the pointer operand. 6762 6763.. code-block:: llvm 6764 6765 %v = load i8, i8* %x, !invariant.group !0 6766 ; if %x mustalias %y then we can replace the above instruction with 6767 %v = load i8, i8* %y 6768 6769Note that this is an experimental feature, which means that its semantics might 6770change in the future. 6771 6772'``type``' Metadata 6773^^^^^^^^^^^^^^^^^^^ 6774 6775See :doc:`TypeMetadata`. 6776 6777'``associated``' Metadata 6778^^^^^^^^^^^^^^^^^^^^^^^^^ 6779 6780The ``associated`` metadata may be attached to a global object 6781declaration with a single argument that references another global object. 6782 6783This metadata prevents discarding of the global object in linker GC 6784unless the referenced object is also discarded. The linker support for 6785this feature is spotty. For best compatibility, globals carrying this 6786metadata may also: 6787 6788- Be in a comdat with the referenced global. 6789- Be in @llvm.compiler.used. 6790- Have an explicit section with a name which is a valid C identifier. 6791 6792It does not have any effect on non-ELF targets. 6793 6794Example: 6795 6796.. code-block:: text 6797 6798 $a = comdat any 6799 @a = global i32 1, comdat $a 6800 @b = internal global i32 2, comdat $a, section "abc", !associated !0 6801 !0 = !{i32* @a} 6802 6803 6804'``prof``' Metadata 6805^^^^^^^^^^^^^^^^^^^ 6806 6807The ``prof`` metadata is used to record profile data in the IR. 6808The first operand of the metadata node indicates the profile metadata 6809type. There are currently 3 types: 6810:ref:`branch_weights<prof_node_branch_weights>`, 6811:ref:`function_entry_count<prof_node_function_entry_count>`, and 6812:ref:`VP<prof_node_VP>`. 6813 6814.. _prof_node_branch_weights: 6815 6816branch_weights 6817"""""""""""""" 6818 6819Branch weight metadata attached to a branch, select, switch or call instruction 6820represents the likeliness of the associated branch being taken. 6821For more information, see :doc:`BranchWeightMetadata`. 6822 6823.. _prof_node_function_entry_count: 6824 6825function_entry_count 6826"""""""""""""""""""" 6827 6828Function entry count metadata can be attached to function definitions 6829to record the number of times the function is called. Used with BFI 6830information, it is also used to derive the basic block profile count. 6831For more information, see :doc:`BranchWeightMetadata`. 6832 6833.. _prof_node_VP: 6834 6835VP 6836"" 6837 6838VP (value profile) metadata can be attached to instructions that have 6839value profile information. Currently this is indirect calls (where it 6840records the hottest callees) and calls to memory intrinsics such as memcpy, 6841memmove, and memset (where it records the hottest byte lengths). 6842 6843Each VP metadata node contains "VP" string, then a uint32_t value for the value 6844profiling kind, a uint64_t value for the total number of times the instruction 6845is executed, followed by uint64_t value and execution count pairs. 6846The value profiling kind is 0 for indirect call targets and 1 for memory 6847operations. For indirect call targets, each profile value is a hash 6848of the callee function name, and for memory operations each value is the 6849byte length. 6850 6851Note that the value counts do not need to add up to the total count 6852listed in the third operand (in practice only the top hottest values 6853are tracked and reported). 6854 6855Indirect call example: 6856 6857.. code-block:: llvm 6858 6859 call void %f(), !prof !1 6860 !1 = !{!"VP", i32 0, i64 1600, i64 7651369219802541373, i64 1030, i64 -4377547752858689819, i64 410} 6861 6862Note that the VP type is 0 (the second operand), which indicates this is 6863an indirect call value profile data. The third operand indicates that the 6864indirect call executed 1600 times. The 4th and 6th operands give the 6865hashes of the 2 hottest target functions' names (this is the same hash used 6866to represent function names in the profile database), and the 5th and 7th 6867operands give the execution count that each of the respective prior target 6868functions was called. 6869 6870.. _md_annotation: 6871 6872'``annotation``' Metadata 6873^^^^^^^^^^^^^^^^^^^^^^^^^ 6874 6875The ``annotation`` metadata can be used to attach a tuple of annotation strings 6876to any instruction. This metadata does not impact the semantics of the program 6877and may only be used to provide additional insight about the program and 6878transformations to users. 6879 6880Example: 6881 6882.. code-block:: text 6883 6884 %a.addr = alloca float*, align 8, !annotation !0 6885 !0 = !{!"auto-init"} 6886 6887Module Flags Metadata 6888===================== 6889 6890Information about the module as a whole is difficult to convey to LLVM's 6891subsystems. The LLVM IR isn't sufficient to transmit this information. 6892The ``llvm.module.flags`` named metadata exists in order to facilitate 6893this. These flags are in the form of key / value pairs --- much like a 6894dictionary --- making it easy for any subsystem who cares about a flag to 6895look it up. 6896 6897The ``llvm.module.flags`` metadata contains a list of metadata triplets. 6898Each triplet has the following form: 6899 6900- The first element is a *behavior* flag, which specifies the behavior 6901 when two (or more) modules are merged together, and it encounters two 6902 (or more) metadata with the same ID. The supported behaviors are 6903 described below. 6904- The second element is a metadata string that is a unique ID for the 6905 metadata. Each module may only have one flag entry for each unique ID (not 6906 including entries with the **Require** behavior). 6907- The third element is the value of the flag. 6908 6909When two (or more) modules are merged together, the resulting 6910``llvm.module.flags`` metadata is the union of the modules' flags. That is, for 6911each unique metadata ID string, there will be exactly one entry in the merged 6912modules ``llvm.module.flags`` metadata table, and the value for that entry will 6913be determined by the merge behavior flag, as described below. The only exception 6914is that entries with the *Require* behavior are always preserved. 6915 6916The following behaviors are supported: 6917 6918.. list-table:: 6919 :header-rows: 1 6920 :widths: 10 90 6921 6922 * - Value 6923 - Behavior 6924 6925 * - 1 6926 - **Error** 6927 Emits an error if two values disagree, otherwise the resulting value 6928 is that of the operands. 6929 6930 * - 2 6931 - **Warning** 6932 Emits a warning if two values disagree. The result value will be the 6933 operand for the flag from the first module being linked, or the max 6934 if the other module uses **Max** (in which case the resulting flag 6935 will be **Max**). 6936 6937 * - 3 6938 - **Require** 6939 Adds a requirement that another module flag be present and have a 6940 specified value after linking is performed. The value must be a 6941 metadata pair, where the first element of the pair is the ID of the 6942 module flag to be restricted, and the second element of the pair is 6943 the value the module flag should be restricted to. This behavior can 6944 be used to restrict the allowable results (via triggering of an 6945 error) of linking IDs with the **Override** behavior. 6946 6947 * - 4 6948 - **Override** 6949 Uses the specified value, regardless of the behavior or value of the 6950 other module. If both modules specify **Override**, but the values 6951 differ, an error will be emitted. 6952 6953 * - 5 6954 - **Append** 6955 Appends the two values, which are required to be metadata nodes. 6956 6957 * - 6 6958 - **AppendUnique** 6959 Appends the two values, which are required to be metadata 6960 nodes. However, duplicate entries in the second list are dropped 6961 during the append operation. 6962 6963 * - 7 6964 - **Max** 6965 Takes the max of the two values, which are required to be integers. 6966 6967It is an error for a particular unique flag ID to have multiple behaviors, 6968except in the case of **Require** (which adds restrictions on another metadata 6969value) or **Override**. 6970 6971An example of module flags: 6972 6973.. code-block:: llvm 6974 6975 !0 = !{ i32 1, !"foo", i32 1 } 6976 !1 = !{ i32 4, !"bar", i32 37 } 6977 !2 = !{ i32 2, !"qux", i32 42 } 6978 !3 = !{ i32 3, !"qux", 6979 !{ 6980 !"foo", i32 1 6981 } 6982 } 6983 !llvm.module.flags = !{ !0, !1, !2, !3 } 6984 6985- Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior 6986 if two or more ``!"foo"`` flags are seen is to emit an error if their 6987 values are not equal. 6988 6989- Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The 6990 behavior if two or more ``!"bar"`` flags are seen is to use the value 6991 '37'. 6992 6993- Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The 6994 behavior if two or more ``!"qux"`` flags are seen is to emit a 6995 warning if their values are not equal. 6996 6997- Metadata ``!3`` has the ID ``!"qux"`` and the value: 6998 6999 :: 7000 7001 !{ !"foo", i32 1 } 7002 7003 The behavior is to emit an error if the ``llvm.module.flags`` does not 7004 contain a flag with the ID ``!"foo"`` that has the value '1' after linking is 7005 performed. 7006 7007Synthesized Functions Module Flags Metadata 7008------------------------------------------- 7009 7010These metadata specify the default attributes synthesized functions should have. 7011These metadata are currently respected by a few instrumentation passes, such as 7012sanitizers. 7013 7014These metadata correspond to a few function attributes with significant code 7015generation behaviors. Function attributes with just optimization purposes 7016should not be listed because the performance impact of these synthesized 7017functions is small. 7018 7019- "frame-pointer": **Max**. The value can be 0, 1, or 2. A synthesized function 7020 will get the "frame-pointer" function attribute, with value being "none", 7021 "non-leaf", or "all", respectively. 7022- "uwtable": **Max**. The value can be 0 or 1. If the value is 1, a synthesized 7023 function will get the ``uwtable`` function attribute. 7024 7025Objective-C Garbage Collection Module Flags Metadata 7026---------------------------------------------------- 7027 7028On the Mach-O platform, Objective-C stores metadata about garbage 7029collection in a special section called "image info". The metadata 7030consists of a version number and a bitmask specifying what types of 7031garbage collection are supported (if any) by the file. If two or more 7032modules are linked together their garbage collection metadata needs to 7033be merged rather than appended together. 7034 7035The Objective-C garbage collection module flags metadata consists of the 7036following key-value pairs: 7037 7038.. list-table:: 7039 :header-rows: 1 7040 :widths: 30 70 7041 7042 * - Key 7043 - Value 7044 7045 * - ``Objective-C Version`` 7046 - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2. 7047 7048 * - ``Objective-C Image Info Version`` 7049 - **[Required]** --- The version of the image info section. Currently 7050 always 0. 7051 7052 * - ``Objective-C Image Info Section`` 7053 - **[Required]** --- The section to place the metadata. Valid values are 7054 ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and 7055 ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for 7056 Objective-C ABI version 2. 7057 7058 * - ``Objective-C Garbage Collection`` 7059 - **[Required]** --- Specifies whether garbage collection is supported or 7060 not. Valid values are 0, for no garbage collection, and 2, for garbage 7061 collection supported. 7062 7063 * - ``Objective-C GC Only`` 7064 - **[Optional]** --- Specifies that only garbage collection is supported. 7065 If present, its value must be 6. This flag requires that the 7066 ``Objective-C Garbage Collection`` flag have the value 2. 7067 7068Some important flag interactions: 7069 7070- If a module with ``Objective-C Garbage Collection`` set to 0 is 7071 merged with a module with ``Objective-C Garbage Collection`` set to 7072 2, then the resulting module has the 7073 ``Objective-C Garbage Collection`` flag set to 0. 7074- A module with ``Objective-C Garbage Collection`` set to 0 cannot be 7075 merged with a module with ``Objective-C GC Only`` set to 6. 7076 7077C type width Module Flags Metadata 7078---------------------------------- 7079 7080The ARM backend emits a section into each generated object file describing the 7081options that it was compiled with (in a compiler-independent way) to prevent 7082linking incompatible objects, and to allow automatic library selection. Some 7083of these options are not visible at the IR level, namely wchar_t width and enum 7084width. 7085 7086To pass this information to the backend, these options are encoded in module 7087flags metadata, using the following key-value pairs: 7088 7089.. list-table:: 7090 :header-rows: 1 7091 :widths: 30 70 7092 7093 * - Key 7094 - Value 7095 7096 * - short_wchar 7097 - * 0 --- sizeof(wchar_t) == 4 7098 * 1 --- sizeof(wchar_t) == 2 7099 7100 * - short_enum 7101 - * 0 --- Enums are at least as large as an ``int``. 7102 * 1 --- Enums are stored in the smallest integer type which can 7103 represent all of its values. 7104 7105For example, the following metadata section specifies that the module was 7106compiled with a ``wchar_t`` width of 4 bytes, and the underlying type of an 7107enum is the smallest type which can represent all of its values:: 7108 7109 !llvm.module.flags = !{!0, !1} 7110 !0 = !{i32 1, !"short_wchar", i32 1} 7111 !1 = !{i32 1, !"short_enum", i32 0} 7112 7113LTO Post-Link Module Flags Metadata 7114----------------------------------- 7115 7116Some optimisations are only when the entire LTO unit is present in the current 7117module. This is represented by the ``LTOPostLink`` module flags metadata, which 7118will be created with a value of ``1`` when LTO linking occurs. 7119 7120Automatic Linker Flags Named Metadata 7121===================================== 7122 7123Some targets support embedding of flags to the linker inside individual object 7124files. Typically this is used in conjunction with language extensions which 7125allow source files to contain linker command line options, and have these 7126automatically be transmitted to the linker via object files. 7127 7128These flags are encoded in the IR using named metadata with the name 7129``!llvm.linker.options``. Each operand is expected to be a metadata node 7130which should be a list of other metadata nodes, each of which should be a 7131list of metadata strings defining linker options. 7132 7133For example, the following metadata section specifies two separate sets of 7134linker options, presumably to link against ``libz`` and the ``Cocoa`` 7135framework:: 7136 7137 !0 = !{ !"-lz" } 7138 !1 = !{ !"-framework", !"Cocoa" } 7139 !llvm.linker.options = !{ !0, !1 } 7140 7141The metadata encoding as lists of lists of options, as opposed to a collapsed 7142list of options, is chosen so that the IR encoding can use multiple option 7143strings to specify e.g., a single library, while still having that specifier be 7144preserved as an atomic element that can be recognized by a target specific 7145assembly writer or object file emitter. 7146 7147Each individual option is required to be either a valid option for the target's 7148linker, or an option that is reserved by the target specific assembly writer or 7149object file emitter. No other aspect of these options is defined by the IR. 7150 7151Dependent Libs Named Metadata 7152============================= 7153 7154Some targets support embedding of strings into object files to indicate 7155a set of libraries to add to the link. Typically this is used in conjunction 7156with language extensions which allow source files to explicitly declare the 7157libraries they depend on, and have these automatically be transmitted to the 7158linker via object files. 7159 7160The list is encoded in the IR using named metadata with the name 7161``!llvm.dependent-libraries``. Each operand is expected to be a metadata node 7162which should contain a single string operand. 7163 7164For example, the following metadata section contains two library specifiers:: 7165 7166 !0 = !{!"a library specifier"} 7167 !1 = !{!"another library specifier"} 7168 !llvm.dependent-libraries = !{ !0, !1 } 7169 7170Each library specifier will be handled independently by the consuming linker. 7171The effect of the library specifiers are defined by the consuming linker. 7172 7173.. _summary: 7174 7175ThinLTO Summary 7176=============== 7177 7178Compiling with `ThinLTO <https://clang.llvm.org/docs/ThinLTO.html>`_ 7179causes the building of a compact summary of the module that is emitted into 7180the bitcode. The summary is emitted into the LLVM assembly and identified 7181in syntax by a caret ('``^``'). 7182 7183The summary is parsed into a bitcode output, along with the Module 7184IR, via the "``llvm-as``" tool. Tools that parse the Module IR for the purposes 7185of optimization (e.g. "``clang -x ir``" and "``opt``"), will ignore the 7186summary entries (just as they currently ignore summary entries in a bitcode 7187input file). 7188 7189Eventually, the summary will be parsed into a ModuleSummaryIndex object under 7190the same conditions where summary index is currently built from bitcode. 7191Specifically, tools that test the Thin Link portion of a ThinLTO compile 7192(i.e. llvm-lto and llvm-lto2), or when parsing a combined index 7193for a distributed ThinLTO backend via clang's "``-fthinlto-index=<>``" flag 7194(this part is not yet implemented, use llvm-as to create a bitcode object 7195before feeding into thin link tools for now). 7196 7197There are currently 3 types of summary entries in the LLVM assembly: 7198:ref:`module paths<module_path_summary>`, 7199:ref:`global values<gv_summary>`, and 7200:ref:`type identifiers<typeid_summary>`. 7201 7202.. _module_path_summary: 7203 7204Module Path Summary Entry 7205------------------------- 7206 7207Each module path summary entry lists a module containing global values included 7208in the summary. For a single IR module there will be one such entry, but 7209in a combined summary index produced during the thin link, there will be 7210one module path entry per linked module with summary. 7211 7212Example: 7213 7214.. code-block:: text 7215 7216 ^0 = module: (path: "/path/to/file.o", hash: (2468601609, 1329373163, 1565878005, 638838075, 3148790418)) 7217 7218The ``path`` field is a string path to the bitcode file, and the ``hash`` 7219field is the 160-bit SHA-1 hash of the IR bitcode contents, used for 7220incremental builds and caching. 7221 7222.. _gv_summary: 7223 7224Global Value Summary Entry 7225-------------------------- 7226 7227Each global value summary entry corresponds to a global value defined or 7228referenced by a summarized module. 7229 7230Example: 7231 7232.. code-block:: text 7233 7234 ^4 = gv: (name: "f"[, summaries: (Summary)[, (Summary)]*]?) ; guid = 14740650423002898831 7235 7236For declarations, there will not be a summary list. For definitions, a 7237global value will contain a list of summaries, one per module containing 7238a definition. There can be multiple entries in a combined summary index 7239for symbols with weak linkage. 7240 7241Each ``Summary`` format will depend on whether the global value is a 7242:ref:`function<function_summary>`, :ref:`variable<variable_summary>`, or 7243:ref:`alias<alias_summary>`. 7244 7245.. _function_summary: 7246 7247Function Summary 7248^^^^^^^^^^^^^^^^ 7249 7250If the global value is a function, the ``Summary`` entry will look like: 7251 7252.. code-block:: text 7253 7254 function: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), insts: 2[, FuncFlags]?[, Calls]?[, TypeIdInfo]?[, Params]?[, Refs]? 7255 7256The ``module`` field includes the summary entry id for the module containing 7257this definition, and the ``flags`` field contains information such as 7258the linkage type, a flag indicating whether it is legal to import the 7259definition, whether it is globally live and whether the linker resolved it 7260to a local definition (the latter two are populated during the thin link). 7261The ``insts`` field contains the number of IR instructions in the function. 7262Finally, there are several optional fields: :ref:`FuncFlags<funcflags_summary>`, 7263:ref:`Calls<calls_summary>`, :ref:`TypeIdInfo<typeidinfo_summary>`, 7264:ref:`Params<params_summary>`, :ref:`Refs<refs_summary>`. 7265 7266.. _variable_summary: 7267 7268Global Variable Summary 7269^^^^^^^^^^^^^^^^^^^^^^^ 7270 7271If the global value is a variable, the ``Summary`` entry will look like: 7272 7273.. code-block:: text 7274 7275 variable: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0)[, Refs]? 7276 7277The variable entry contains a subset of the fields in a 7278:ref:`function summary <function_summary>`, see the descriptions there. 7279 7280.. _alias_summary: 7281 7282Alias Summary 7283^^^^^^^^^^^^^ 7284 7285If the global value is an alias, the ``Summary`` entry will look like: 7286 7287.. code-block:: text 7288 7289 alias: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), aliasee: ^2) 7290 7291The ``module`` and ``flags`` fields are as described for a 7292:ref:`function summary <function_summary>`. The ``aliasee`` field 7293contains a reference to the global value summary entry of the aliasee. 7294 7295.. _funcflags_summary: 7296 7297Function Flags 7298^^^^^^^^^^^^^^ 7299 7300The optional ``FuncFlags`` field looks like: 7301 7302.. code-block:: text 7303 7304 funcFlags: (readNone: 0, readOnly: 0, noRecurse: 0, returnDoesNotAlias: 0) 7305 7306If unspecified, flags are assumed to hold the conservative ``false`` value of 7307``0``. 7308 7309.. _calls_summary: 7310 7311Calls 7312^^^^^ 7313 7314The optional ``Calls`` field looks like: 7315 7316.. code-block:: text 7317 7318 calls: ((Callee)[, (Callee)]*) 7319 7320where each ``Callee`` looks like: 7321 7322.. code-block:: text 7323 7324 callee: ^1[, hotness: None]?[, relbf: 0]? 7325 7326The ``callee`` refers to the summary entry id of the callee. At most one 7327of ``hotness`` (which can take the values ``Unknown``, ``Cold``, ``None``, 7328``Hot``, and ``Critical``), and ``relbf`` (which holds the integer 7329branch frequency relative to the entry frequency, scaled down by 2^8) 7330may be specified. The defaults are ``Unknown`` and ``0``, respectively. 7331 7332.. _params_summary: 7333 7334Params 7335^^^^^^ 7336 7337The optional ``Params`` is used by ``StackSafety`` and looks like: 7338 7339.. code-block:: text 7340 7341 Params: ((Param)[, (Param)]*) 7342 7343where each ``Param`` describes pointer parameter access inside of the 7344function and looks like: 7345 7346.. code-block:: text 7347 7348 param: 4, offset: [0, 5][, calls: ((Callee)[, (Callee)]*)]? 7349 7350where the first ``param`` is the number of the parameter it describes, 7351``offset`` is the inclusive range of offsets from the pointer parameter to bytes 7352which can be accessed by the function. This range does not include accesses by 7353function calls from ``calls`` list. 7354 7355where each ``Callee`` describes how parameter is forwarded into other 7356functions and looks like: 7357 7358.. code-block:: text 7359 7360 callee: ^3, param: 5, offset: [-3, 3] 7361 7362The ``callee`` refers to the summary entry id of the callee, ``param`` is 7363the number of the callee parameter which points into the callers parameter 7364with offset known to be inside of the ``offset`` range. ``calls`` will be 7365consumed and removed by thin link stage to update ``Param::offset`` so it 7366covers all accesses possible by ``calls``. 7367 7368Pointer parameter without corresponding ``Param`` is considered unsafe and we 7369assume that access with any offset is possible. 7370 7371Example: 7372 7373If we have the following function: 7374 7375.. code-block:: text 7376 7377 define i64 @foo(i64* %0, i32* %1, i8* %2, i8 %3) { 7378 store i32* %1, i32** @x 7379 %5 = getelementptr inbounds i8, i8* %2, i64 5 7380 %6 = load i8, i8* %5 7381 %7 = getelementptr inbounds i8, i8* %2, i8 %3 7382 tail call void @bar(i8 %3, i8* %7) 7383 %8 = load i64, i64* %0 7384 ret i64 %8 7385 } 7386 7387We can expect the record like this: 7388 7389.. code-block:: text 7390 7391 params: ((param: 0, offset: [0, 7]),(param: 2, offset: [5, 5], calls: ((callee: ^3, param: 1, offset: [-128, 127])))) 7392 7393The function may access just 8 bytes of the parameter %0 . ``calls`` is empty, 7394so the parameter is either not used for function calls or ``offset`` already 7395covers all accesses from nested function calls. 7396Parameter %1 escapes, so access is unknown. 7397The function itself can access just a single byte of the parameter %2. Additional 7398access is possible inside of the ``@bar`` or ``^3``. The function adds signed 7399offset to the pointer and passes the result as the argument %1 into ``^3``. 7400This record itself does not tell us how ``^3`` will access the parameter. 7401Parameter %3 is not a pointer. 7402 7403.. _refs_summary: 7404 7405Refs 7406^^^^ 7407 7408The optional ``Refs`` field looks like: 7409 7410.. code-block:: text 7411 7412 refs: ((Ref)[, (Ref)]*) 7413 7414where each ``Ref`` contains a reference to the summary id of the referenced 7415value (e.g. ``^1``). 7416 7417.. _typeidinfo_summary: 7418 7419TypeIdInfo 7420^^^^^^^^^^ 7421 7422The optional ``TypeIdInfo`` field, used for 7423`Control Flow Integrity <https://clang.llvm.org/docs/ControlFlowIntegrity.html>`_, 7424looks like: 7425 7426.. code-block:: text 7427 7428 typeIdInfo: [(TypeTests)]?[, (TypeTestAssumeVCalls)]?[, (TypeCheckedLoadVCalls)]?[, (TypeTestAssumeConstVCalls)]?[, (TypeCheckedLoadConstVCalls)]? 7429 7430These optional fields have the following forms: 7431 7432TypeTests 7433""""""""" 7434 7435.. code-block:: text 7436 7437 typeTests: (TypeIdRef[, TypeIdRef]*) 7438 7439Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>` 7440by summary id or ``GUID``. 7441 7442TypeTestAssumeVCalls 7443"""""""""""""""""""" 7444 7445.. code-block:: text 7446 7447 typeTestAssumeVCalls: (VFuncId[, VFuncId]*) 7448 7449Where each VFuncId has the format: 7450 7451.. code-block:: text 7452 7453 vFuncId: (TypeIdRef, offset: 16) 7454 7455Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>` 7456by summary id or ``GUID`` preceded by a ``guid:`` tag. 7457 7458TypeCheckedLoadVCalls 7459""""""""""""""""""""" 7460 7461.. code-block:: text 7462 7463 typeCheckedLoadVCalls: (VFuncId[, VFuncId]*) 7464 7465Where each VFuncId has the format described for ``TypeTestAssumeVCalls``. 7466 7467TypeTestAssumeConstVCalls 7468""""""""""""""""""""""""" 7469 7470.. code-block:: text 7471 7472 typeTestAssumeConstVCalls: (ConstVCall[, ConstVCall]*) 7473 7474Where each ConstVCall has the format: 7475 7476.. code-block:: text 7477 7478 (VFuncId, args: (Arg[, Arg]*)) 7479 7480and where each VFuncId has the format described for ``TypeTestAssumeVCalls``, 7481and each Arg is an integer argument number. 7482 7483TypeCheckedLoadConstVCalls 7484"""""""""""""""""""""""""" 7485 7486.. code-block:: text 7487 7488 typeCheckedLoadConstVCalls: (ConstVCall[, ConstVCall]*) 7489 7490Where each ConstVCall has the format described for 7491``TypeTestAssumeConstVCalls``. 7492 7493.. _typeid_summary: 7494 7495Type ID Summary Entry 7496--------------------- 7497 7498Each type id summary entry corresponds to a type identifier resolution 7499which is generated during the LTO link portion of the compile when building 7500with `Control Flow Integrity <https://clang.llvm.org/docs/ControlFlowIntegrity.html>`_, 7501so these are only present in a combined summary index. 7502 7503Example: 7504 7505.. code-block:: text 7506 7507 ^4 = typeid: (name: "_ZTS1A", summary: (typeTestRes: (kind: allOnes, sizeM1BitWidth: 7[, alignLog2: 0]?[, sizeM1: 0]?[, bitMask: 0]?[, inlineBits: 0]?)[, WpdResolutions]?)) ; guid = 7004155349499253778 7508 7509The ``typeTestRes`` gives the type test resolution ``kind`` (which may 7510be ``unsat``, ``byteArray``, ``inline``, ``single``, or ``allOnes``), and 7511the ``size-1`` bit width. It is followed by optional flags, which default to 0, 7512and an optional WpdResolutions (whole program devirtualization resolution) 7513field that looks like: 7514 7515.. code-block:: text 7516 7517 wpdResolutions: ((offset: 0, WpdRes)[, (offset: 1, WpdRes)]* 7518 7519where each entry is a mapping from the given byte offset to the whole-program 7520devirtualization resolution WpdRes, that has one of the following formats: 7521 7522.. code-block:: text 7523 7524 wpdRes: (kind: branchFunnel) 7525 wpdRes: (kind: singleImpl, singleImplName: "_ZN1A1nEi") 7526 wpdRes: (kind: indir) 7527 7528Additionally, each wpdRes has an optional ``resByArg`` field, which 7529describes the resolutions for calls with all constant integer arguments: 7530 7531.. code-block:: text 7532 7533 resByArg: (ResByArg[, ResByArg]*) 7534 7535where ResByArg is: 7536 7537.. code-block:: text 7538 7539 args: (Arg[, Arg]*), byArg: (kind: UniformRetVal[, info: 0][, byte: 0][, bit: 0]) 7540 7541Where the ``kind`` can be ``Indir``, ``UniformRetVal``, ``UniqueRetVal`` 7542or ``VirtualConstProp``. The ``info`` field is only used if the kind 7543is ``UniformRetVal`` (indicates the uniform return value), or 7544``UniqueRetVal`` (holds the return value associated with the unique vtable 7545(0 or 1)). The ``byte`` and ``bit`` fields are only used if the target does 7546not support the use of absolute symbols to store constants. 7547 7548.. _intrinsicglobalvariables: 7549 7550Intrinsic Global Variables 7551========================== 7552 7553LLVM has a number of "magic" global variables that contain data that 7554affect code generation or other IR semantics. These are documented here. 7555All globals of this sort should have a section specified as 7556"``llvm.metadata``". This section and all globals that start with 7557"``llvm.``" are reserved for use by LLVM. 7558 7559.. _gv_llvmused: 7560 7561The '``llvm.used``' Global Variable 7562----------------------------------- 7563 7564The ``@llvm.used`` global is an array which has 7565:ref:`appending linkage <linkage_appending>`. This array contains a list of 7566pointers to named global variables, functions and aliases which may optionally 7567have a pointer cast formed of bitcast or getelementptr. For example, a legal 7568use of it is: 7569 7570.. code-block:: llvm 7571 7572 @X = global i8 4 7573 @Y = global i32 123 7574 7575 @llvm.used = appending global [2 x i8*] [ 7576 i8* @X, 7577 i8* bitcast (i32* @Y to i8*) 7578 ], section "llvm.metadata" 7579 7580If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler, 7581and linker are required to treat the symbol as if there is a reference to the 7582symbol that it cannot see (which is why they have to be named). For example, if 7583a variable has internal linkage and no references other than that from the 7584``@llvm.used`` list, it cannot be deleted. This is commonly used to represent 7585references from inline asms and other things the compiler cannot "see", and 7586corresponds to "``attribute((used))``" in GNU C. 7587 7588On some targets, the code generator must emit a directive to the 7589assembler or object file to prevent the assembler and linker from 7590removing the symbol. 7591 7592.. _gv_llvmcompilerused: 7593 7594The '``llvm.compiler.used``' Global Variable 7595-------------------------------------------- 7596 7597The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used`` 7598directive, except that it only prevents the compiler from touching the 7599symbol. On targets that support it, this allows an intelligent linker to 7600optimize references to the symbol without being impeded as it would be 7601by ``@llvm.used``. 7602 7603This is a rare construct that should only be used in rare circumstances, 7604and should not be exposed to source languages. 7605 7606.. _gv_llvmglobalctors: 7607 7608The '``llvm.global_ctors``' Global Variable 7609------------------------------------------- 7610 7611.. code-block:: llvm 7612 7613 %0 = type { i32, void ()*, i8* } 7614 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor, i8* @data }] 7615 7616The ``@llvm.global_ctors`` array contains a list of constructor 7617functions, priorities, and an associated global or function. 7618The functions referenced by this array will be called in ascending order 7619of priority (i.e. lowest first) when the module is loaded. The order of 7620functions with the same priority is not defined. 7621 7622If the third field is non-null, and points to a global variable 7623or function, the initializer function will only run if the associated 7624data from the current module is not discarded. 7625 7626.. _llvmglobaldtors: 7627 7628The '``llvm.global_dtors``' Global Variable 7629------------------------------------------- 7630 7631.. code-block:: llvm 7632 7633 %0 = type { i32, void ()*, i8* } 7634 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor, i8* @data }] 7635 7636The ``@llvm.global_dtors`` array contains a list of destructor 7637functions, priorities, and an associated global or function. 7638The functions referenced by this array will be called in descending 7639order of priority (i.e. highest first) when the module is unloaded. The 7640order of functions with the same priority is not defined. 7641 7642If the third field is non-null, and points to a global variable 7643or function, the destructor function will only run if the associated 7644data from the current module is not discarded. 7645 7646Instruction Reference 7647===================== 7648 7649The LLVM instruction set consists of several different classifications 7650of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary 7651instructions <binaryops>`, :ref:`bitwise binary 7652instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and 7653:ref:`other instructions <otherops>`. 7654 7655.. _terminators: 7656 7657Terminator Instructions 7658----------------------- 7659 7660As mentioned :ref:`previously <functionstructure>`, every basic block in a 7661program ends with a "Terminator" instruction, which indicates which 7662block should be executed after the current block is finished. These 7663terminator instructions typically yield a '``void``' value: they produce 7664control flow, not values (the one exception being the 7665':ref:`invoke <i_invoke>`' instruction). 7666 7667The terminator instructions are: ':ref:`ret <i_ret>`', 7668':ref:`br <i_br>`', ':ref:`switch <i_switch>`', 7669':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`', 7670':ref:`callbr <i_callbr>`' 7671':ref:`resume <i_resume>`', ':ref:`catchswitch <i_catchswitch>`', 7672':ref:`catchret <i_catchret>`', 7673':ref:`cleanupret <i_cleanupret>`', 7674and ':ref:`unreachable <i_unreachable>`'. 7675 7676.. _i_ret: 7677 7678'``ret``' Instruction 7679^^^^^^^^^^^^^^^^^^^^^ 7680 7681Syntax: 7682""""""" 7683 7684:: 7685 7686 ret <type> <value> ; Return a value from a non-void function 7687 ret void ; Return from void function 7688 7689Overview: 7690""""""""" 7691 7692The '``ret``' instruction is used to return control flow (and optionally 7693a value) from a function back to the caller. 7694 7695There are two forms of the '``ret``' instruction: one that returns a 7696value and then causes control flow, and one that just causes control 7697flow to occur. 7698 7699Arguments: 7700"""""""""" 7701 7702The '``ret``' instruction optionally accepts a single argument, the 7703return value. The type of the return value must be a ':ref:`first 7704class <t_firstclass>`' type. 7705 7706A function is not :ref:`well formed <wellformed>` if it has a non-void 7707return type and contains a '``ret``' instruction with no return value or 7708a return value with a type that does not match its type, or if it has a 7709void return type and contains a '``ret``' instruction with a return 7710value. 7711 7712Semantics: 7713"""""""""" 7714 7715When the '``ret``' instruction is executed, control flow returns back to 7716the calling function's context. If the caller is a 7717":ref:`call <i_call>`" instruction, execution continues at the 7718instruction after the call. If the caller was an 7719":ref:`invoke <i_invoke>`" instruction, execution continues at the 7720beginning of the "normal" destination block. If the instruction returns 7721a value, that value shall set the call or invoke instruction's return 7722value. 7723 7724Example: 7725"""""""" 7726 7727.. code-block:: llvm 7728 7729 ret i32 5 ; Return an integer value of 5 7730 ret void ; Return from a void function 7731 ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2 7732 7733.. _i_br: 7734 7735'``br``' Instruction 7736^^^^^^^^^^^^^^^^^^^^ 7737 7738Syntax: 7739""""""" 7740 7741:: 7742 7743 br i1 <cond>, label <iftrue>, label <iffalse> 7744 br label <dest> ; Unconditional branch 7745 7746Overview: 7747""""""""" 7748 7749The '``br``' instruction is used to cause control flow to transfer to a 7750different basic block in the current function. There are two forms of 7751this instruction, corresponding to a conditional branch and an 7752unconditional branch. 7753 7754Arguments: 7755"""""""""" 7756 7757The conditional branch form of the '``br``' instruction takes a single 7758'``i1``' value and two '``label``' values. The unconditional form of the 7759'``br``' instruction takes a single '``label``' value as a target. 7760 7761Semantics: 7762"""""""""" 7763 7764Upon execution of a conditional '``br``' instruction, the '``i1``' 7765argument is evaluated. If the value is ``true``, control flows to the 7766'``iftrue``' ``label`` argument. If "cond" is ``false``, control flows 7767to the '``iffalse``' ``label`` argument. 7768If '``cond``' is ``poison`` or ``undef``, this instruction has undefined 7769behavior. 7770 7771Example: 7772"""""""" 7773 7774.. code-block:: llvm 7775 7776 Test: 7777 %cond = icmp eq i32 %a, %b 7778 br i1 %cond, label %IfEqual, label %IfUnequal 7779 IfEqual: 7780 ret i32 1 7781 IfUnequal: 7782 ret i32 0 7783 7784.. _i_switch: 7785 7786'``switch``' Instruction 7787^^^^^^^^^^^^^^^^^^^^^^^^ 7788 7789Syntax: 7790""""""" 7791 7792:: 7793 7794 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ] 7795 7796Overview: 7797""""""""" 7798 7799The '``switch``' instruction is used to transfer control flow to one of 7800several different places. It is a generalization of the '``br``' 7801instruction, allowing a branch to occur to one of many possible 7802destinations. 7803 7804Arguments: 7805"""""""""" 7806 7807The '``switch``' instruction uses three parameters: an integer 7808comparison value '``value``', a default '``label``' destination, and an 7809array of pairs of comparison value constants and '``label``'s. The table 7810is not allowed to contain duplicate constant entries. 7811 7812Semantics: 7813"""""""""" 7814 7815The ``switch`` instruction specifies a table of values and destinations. 7816When the '``switch``' instruction is executed, this table is searched 7817for the given value. If the value is found, control flow is transferred 7818to the corresponding destination; otherwise, control flow is transferred 7819to the default destination. 7820If '``value``' is ``poison`` or ``undef``, this instruction has undefined 7821behavior. 7822 7823Implementation: 7824""""""""""""""" 7825 7826Depending on properties of the target machine and the particular 7827``switch`` instruction, this instruction may be code generated in 7828different ways. For example, it could be generated as a series of 7829chained conditional branches or with a lookup table. 7830 7831Example: 7832"""""""" 7833 7834.. code-block:: llvm 7835 7836 ; Emulate a conditional br instruction 7837 %Val = zext i1 %value to i32 7838 switch i32 %Val, label %truedest [ i32 0, label %falsedest ] 7839 7840 ; Emulate an unconditional br instruction 7841 switch i32 0, label %dest [ ] 7842 7843 ; Implement a jump table: 7844 switch i32 %val, label %otherwise [ i32 0, label %onzero 7845 i32 1, label %onone 7846 i32 2, label %ontwo ] 7847 7848.. _i_indirectbr: 7849 7850'``indirectbr``' Instruction 7851^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 7852 7853Syntax: 7854""""""" 7855 7856:: 7857 7858 indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ] 7859 7860Overview: 7861""""""""" 7862 7863The '``indirectbr``' instruction implements an indirect branch to a 7864label within the current function, whose address is specified by 7865"``address``". Address must be derived from a 7866:ref:`blockaddress <blockaddress>` constant. 7867 7868Arguments: 7869"""""""""" 7870 7871The '``address``' argument is the address of the label to jump to. The 7872rest of the arguments indicate the full set of possible destinations 7873that the address may point to. Blocks are allowed to occur multiple 7874times in the destination list, though this isn't particularly useful. 7875 7876This destination list is required so that dataflow analysis has an 7877accurate understanding of the CFG. 7878 7879Semantics: 7880"""""""""" 7881 7882Control transfers to the block specified in the address argument. All 7883possible destination blocks must be listed in the label list, otherwise 7884this instruction has undefined behavior. This implies that jumps to 7885labels defined in other functions have undefined behavior as well. 7886If '``address``' is ``poison`` or ``undef``, this instruction has undefined 7887behavior. 7888 7889Implementation: 7890""""""""""""""" 7891 7892This is typically implemented with a jump through a register. 7893 7894Example: 7895"""""""" 7896 7897.. code-block:: llvm 7898 7899 indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ] 7900 7901.. _i_invoke: 7902 7903'``invoke``' Instruction 7904^^^^^^^^^^^^^^^^^^^^^^^^ 7905 7906Syntax: 7907""""""" 7908 7909:: 7910 7911 <result> = invoke [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] 7912 [operand bundles] to label <normal label> unwind label <exception label> 7913 7914Overview: 7915""""""""" 7916 7917The '``invoke``' instruction causes control to transfer to a specified 7918function, with the possibility of control flow transfer to either the 7919'``normal``' label or the '``exception``' label. If the callee function 7920returns with the "``ret``" instruction, control flow will return to the 7921"normal" label. If the callee (or any indirect callees) returns via the 7922":ref:`resume <i_resume>`" instruction or other exception handling 7923mechanism, control is interrupted and continued at the dynamically 7924nearest "exception" label. 7925 7926The '``exception``' label is a `landing 7927pad <ExceptionHandling.html#overview>`_ for the exception. As such, 7928'``exception``' label is required to have the 7929":ref:`landingpad <i_landingpad>`" instruction, which contains the 7930information about the behavior of the program after unwinding happens, 7931as its first non-PHI instruction. The restrictions on the 7932"``landingpad``" instruction's tightly couples it to the "``invoke``" 7933instruction, so that the important information contained within the 7934"``landingpad``" instruction can't be lost through normal code motion. 7935 7936Arguments: 7937"""""""""" 7938 7939This instruction requires several arguments: 7940 7941#. The optional "cconv" marker indicates which :ref:`calling 7942 convention <callingconv>` the call should use. If none is 7943 specified, the call defaults to using C calling conventions. 7944#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 7945 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 7946 are valid here. 7947#. The optional addrspace attribute can be used to indicate the address space 7948 of the called function. If it is not specified, the program address space 7949 from the :ref:`datalayout string<langref_datalayout>` will be used. 7950#. '``ty``': the type of the call instruction itself which is also the 7951 type of the return value. Functions that return no value are marked 7952 ``void``. 7953#. '``fnty``': shall be the signature of the function being invoked. The 7954 argument types must match the types implied by this signature. This 7955 type can be omitted if the function is not varargs. 7956#. '``fnptrval``': An LLVM value containing a pointer to a function to 7957 be invoked. In most cases, this is a direct function invocation, but 7958 indirect ``invoke``'s are just as possible, calling an arbitrary pointer 7959 to function value. 7960#. '``function args``': argument list whose types match the function 7961 signature argument types and parameter attributes. All arguments must 7962 be of :ref:`first class <t_firstclass>` type. If the function signature 7963 indicates the function accepts a variable number of arguments, the 7964 extra arguments can be specified. 7965#. '``normal label``': the label reached when the called function 7966 executes a '``ret``' instruction. 7967#. '``exception label``': the label reached when a callee returns via 7968 the :ref:`resume <i_resume>` instruction or other exception handling 7969 mechanism. 7970#. The optional :ref:`function attributes <fnattrs>` list. 7971#. The optional :ref:`operand bundles <opbundles>` list. 7972 7973Semantics: 7974"""""""""" 7975 7976This instruction is designed to operate as a standard '``call``' 7977instruction in most regards. The primary difference is that it 7978establishes an association with a label, which is used by the runtime 7979library to unwind the stack. 7980 7981This instruction is used in languages with destructors to ensure that 7982proper cleanup is performed in the case of either a ``longjmp`` or a 7983thrown exception. Additionally, this is important for implementation of 7984'``catch``' clauses in high-level languages that support them. 7985 7986For the purposes of the SSA form, the definition of the value returned 7987by the '``invoke``' instruction is deemed to occur on the edge from the 7988current block to the "normal" label. If the callee unwinds then no 7989return value is available. 7990 7991Example: 7992"""""""" 7993 7994.. code-block:: llvm 7995 7996 %retval = invoke i32 @Test(i32 15) to label %Continue 7997 unwind label %TestCleanup ; i32:retval set 7998 %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue 7999 unwind label %TestCleanup ; i32:retval set 8000 8001.. _i_callbr: 8002 8003'``callbr``' Instruction 8004^^^^^^^^^^^^^^^^^^^^^^^^ 8005 8006Syntax: 8007""""""" 8008 8009:: 8010 8011 <result> = callbr [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] 8012 [operand bundles] to label <fallthrough label> [indirect labels] 8013 8014Overview: 8015""""""""" 8016 8017The '``callbr``' instruction causes control to transfer to a specified 8018function, with the possibility of control flow transfer to either the 8019'``fallthrough``' label or one of the '``indirect``' labels. 8020 8021This instruction should only be used to implement the "goto" feature of gcc 8022style inline assembly. Any other usage is an error in the IR verifier. 8023 8024Arguments: 8025"""""""""" 8026 8027This instruction requires several arguments: 8028 8029#. The optional "cconv" marker indicates which :ref:`calling 8030 convention <callingconv>` the call should use. If none is 8031 specified, the call defaults to using C calling conventions. 8032#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 8033 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 8034 are valid here. 8035#. The optional addrspace attribute can be used to indicate the address space 8036 of the called function. If it is not specified, the program address space 8037 from the :ref:`datalayout string<langref_datalayout>` will be used. 8038#. '``ty``': the type of the call instruction itself which is also the 8039 type of the return value. Functions that return no value are marked 8040 ``void``. 8041#. '``fnty``': shall be the signature of the function being called. The 8042 argument types must match the types implied by this signature. This 8043 type can be omitted if the function is not varargs. 8044#. '``fnptrval``': An LLVM value containing a pointer to a function to 8045 be called. In most cases, this is a direct function call, but 8046 other ``callbr``'s are just as possible, calling an arbitrary pointer 8047 to function value. 8048#. '``function args``': argument list whose types match the function 8049 signature argument types and parameter attributes. All arguments must 8050 be of :ref:`first class <t_firstclass>` type. If the function signature 8051 indicates the function accepts a variable number of arguments, the 8052 extra arguments can be specified. 8053#. '``fallthrough label``': the label reached when the inline assembly's 8054 execution exits the bottom. 8055#. '``indirect labels``': the labels reached when a callee transfers control 8056 to a location other than the '``fallthrough label``'. The blockaddress 8057 constant for these should also be in the list of '``function args``'. 8058#. The optional :ref:`function attributes <fnattrs>` list. 8059#. The optional :ref:`operand bundles <opbundles>` list. 8060 8061Semantics: 8062"""""""""" 8063 8064This instruction is designed to operate as a standard '``call``' 8065instruction in most regards. The primary difference is that it 8066establishes an association with additional labels to define where control 8067flow goes after the call. 8068 8069The output values of a '``callbr``' instruction are available only to 8070the '``fallthrough``' block, not to any '``indirect``' blocks(s). 8071 8072The only use of this today is to implement the "goto" feature of gcc inline 8073assembly where additional labels can be provided as locations for the inline 8074assembly to jump to. 8075 8076Example: 8077"""""""" 8078 8079.. code-block:: llvm 8080 8081 ; "asm goto" without output constraints. 8082 callbr void asm "", "r,X"(i32 %x, i8 *blockaddress(@foo, %indirect)) 8083 to label %fallthrough [label %indirect] 8084 8085 ; "asm goto" with output constraints. 8086 <result> = callbr i32 asm "", "=r,r,X"(i32 %x, i8 *blockaddress(@foo, %indirect)) 8087 to label %fallthrough [label %indirect] 8088 8089.. _i_resume: 8090 8091'``resume``' Instruction 8092^^^^^^^^^^^^^^^^^^^^^^^^ 8093 8094Syntax: 8095""""""" 8096 8097:: 8098 8099 resume <type> <value> 8100 8101Overview: 8102""""""""" 8103 8104The '``resume``' instruction is a terminator instruction that has no 8105successors. 8106 8107Arguments: 8108"""""""""" 8109 8110The '``resume``' instruction requires one argument, which must have the 8111same type as the result of any '``landingpad``' instruction in the same 8112function. 8113 8114Semantics: 8115"""""""""" 8116 8117The '``resume``' instruction resumes propagation of an existing 8118(in-flight) exception whose unwinding was interrupted with a 8119:ref:`landingpad <i_landingpad>` instruction. 8120 8121Example: 8122"""""""" 8123 8124.. code-block:: llvm 8125 8126 resume { i8*, i32 } %exn 8127 8128.. _i_catchswitch: 8129 8130'``catchswitch``' Instruction 8131^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8132 8133Syntax: 8134""""""" 8135 8136:: 8137 8138 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller 8139 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default> 8140 8141Overview: 8142""""""""" 8143 8144The '``catchswitch``' instruction is used by `LLVM's exception handling system 8145<ExceptionHandling.html#overview>`_ to describe the set of possible catch handlers 8146that may be executed by the :ref:`EH personality routine <personalityfn>`. 8147 8148Arguments: 8149"""""""""" 8150 8151The ``parent`` argument is the token of the funclet that contains the 8152``catchswitch`` instruction. If the ``catchswitch`` is not inside a funclet, 8153this operand may be the token ``none``. 8154 8155The ``default`` argument is the label of another basic block beginning with 8156either a ``cleanuppad`` or ``catchswitch`` instruction. This unwind destination 8157must be a legal target with respect to the ``parent`` links, as described in 8158the `exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_. 8159 8160The ``handlers`` are a nonempty list of successor blocks that each begin with a 8161:ref:`catchpad <i_catchpad>` instruction. 8162 8163Semantics: 8164"""""""""" 8165 8166Executing this instruction transfers control to one of the successors in 8167``handlers``, if appropriate, or continues to unwind via the unwind label if 8168present. 8169 8170The ``catchswitch`` is both a terminator and a "pad" instruction, meaning that 8171it must be both the first non-phi instruction and last instruction in the basic 8172block. Therefore, it must be the only non-phi instruction in the block. 8173 8174Example: 8175"""""""" 8176 8177.. code-block:: text 8178 8179 dispatch1: 8180 %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to caller 8181 dispatch2: 8182 %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup 8183 8184.. _i_catchret: 8185 8186'``catchret``' Instruction 8187^^^^^^^^^^^^^^^^^^^^^^^^^^ 8188 8189Syntax: 8190""""""" 8191 8192:: 8193 8194 catchret from <token> to label <normal> 8195 8196Overview: 8197""""""""" 8198 8199The '``catchret``' instruction is a terminator instruction that has a 8200single successor. 8201 8202 8203Arguments: 8204"""""""""" 8205 8206The first argument to a '``catchret``' indicates which ``catchpad`` it 8207exits. It must be a :ref:`catchpad <i_catchpad>`. 8208The second argument to a '``catchret``' specifies where control will 8209transfer to next. 8210 8211Semantics: 8212"""""""""" 8213 8214The '``catchret``' instruction ends an existing (in-flight) exception whose 8215unwinding was interrupted with a :ref:`catchpad <i_catchpad>` instruction. The 8216:ref:`personality function <personalityfn>` gets a chance to execute arbitrary 8217code to, for example, destroy the active exception. Control then transfers to 8218``normal``. 8219 8220The ``token`` argument must be a token produced by a ``catchpad`` instruction. 8221If the specified ``catchpad`` is not the most-recently-entered not-yet-exited 8222funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 8223the ``catchret``'s behavior is undefined. 8224 8225Example: 8226"""""""" 8227 8228.. code-block:: text 8229 8230 catchret from %catch label %continue 8231 8232.. _i_cleanupret: 8233 8234'``cleanupret``' Instruction 8235^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8236 8237Syntax: 8238""""""" 8239 8240:: 8241 8242 cleanupret from <value> unwind label <continue> 8243 cleanupret from <value> unwind to caller 8244 8245Overview: 8246""""""""" 8247 8248The '``cleanupret``' instruction is a terminator instruction that has 8249an optional successor. 8250 8251 8252Arguments: 8253"""""""""" 8254 8255The '``cleanupret``' instruction requires one argument, which indicates 8256which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_cleanuppad>`. 8257If the specified ``cleanuppad`` is not the most-recently-entered not-yet-exited 8258funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 8259the ``cleanupret``'s behavior is undefined. 8260 8261The '``cleanupret``' instruction also has an optional successor, ``continue``, 8262which must be the label of another basic block beginning with either a 8263``cleanuppad`` or ``catchswitch`` instruction. This unwind destination must 8264be a legal target with respect to the ``parent`` links, as described in the 8265`exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_. 8266 8267Semantics: 8268"""""""""" 8269 8270The '``cleanupret``' instruction indicates to the 8271:ref:`personality function <personalityfn>` that one 8272:ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended. 8273It transfers control to ``continue`` or unwinds out of the function. 8274 8275Example: 8276"""""""" 8277 8278.. code-block:: text 8279 8280 cleanupret from %cleanup unwind to caller 8281 cleanupret from %cleanup unwind label %continue 8282 8283.. _i_unreachable: 8284 8285'``unreachable``' Instruction 8286^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8287 8288Syntax: 8289""""""" 8290 8291:: 8292 8293 unreachable 8294 8295Overview: 8296""""""""" 8297 8298The '``unreachable``' instruction has no defined semantics. This 8299instruction is used to inform the optimizer that a particular portion of 8300the code is not reachable. This can be used to indicate that the code 8301after a no-return function cannot be reached, and other facts. 8302 8303Semantics: 8304"""""""""" 8305 8306The '``unreachable``' instruction has no defined semantics. 8307 8308.. _unaryops: 8309 8310Unary Operations 8311----------------- 8312 8313Unary operators require a single operand, execute an operation on 8314it, and produce a single value. The operand might represent multiple 8315data, as is the case with the :ref:`vector <t_vector>` data type. The 8316result value has the same type as its operand. 8317 8318.. _i_fneg: 8319 8320'``fneg``' Instruction 8321^^^^^^^^^^^^^^^^^^^^^^ 8322 8323Syntax: 8324""""""" 8325 8326:: 8327 8328 <result> = fneg [fast-math flags]* <ty> <op1> ; yields ty:result 8329 8330Overview: 8331""""""""" 8332 8333The '``fneg``' instruction returns the negation of its operand. 8334 8335Arguments: 8336"""""""""" 8337 8338The argument to the '``fneg``' instruction must be a 8339:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8340floating-point values. 8341 8342Semantics: 8343"""""""""" 8344 8345The value produced is a copy of the operand with its sign bit flipped. 8346This instruction can also take any number of :ref:`fast-math 8347flags <fastmath>`, which are optimization hints to enable otherwise 8348unsafe floating-point optimizations: 8349 8350Example: 8351"""""""" 8352 8353.. code-block:: text 8354 8355 <result> = fneg float %val ; yields float:result = -%var 8356 8357.. _binaryops: 8358 8359Binary Operations 8360----------------- 8361 8362Binary operators are used to do most of the computation in a program. 8363They require two operands of the same type, execute an operation on 8364them, and produce a single value. The operands might represent multiple 8365data, as is the case with the :ref:`vector <t_vector>` data type. The 8366result value has the same type as its operands. 8367 8368There are several different binary operators: 8369 8370.. _i_add: 8371 8372'``add``' Instruction 8373^^^^^^^^^^^^^^^^^^^^^ 8374 8375Syntax: 8376""""""" 8377 8378:: 8379 8380 <result> = add <ty> <op1>, <op2> ; yields ty:result 8381 <result> = add nuw <ty> <op1>, <op2> ; yields ty:result 8382 <result> = add nsw <ty> <op1>, <op2> ; yields ty:result 8383 <result> = add nuw nsw <ty> <op1>, <op2> ; yields ty:result 8384 8385Overview: 8386""""""""" 8387 8388The '``add``' instruction returns the sum of its two operands. 8389 8390Arguments: 8391"""""""""" 8392 8393The two arguments to the '``add``' instruction must be 8394:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8395arguments must have identical types. 8396 8397Semantics: 8398"""""""""" 8399 8400The value produced is the integer sum of the two operands. 8401 8402If the sum has unsigned overflow, the result returned is the 8403mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of 8404the result. 8405 8406Because LLVM integers use a two's complement representation, this 8407instruction is appropriate for both signed and unsigned integers. 8408 8409``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 8410respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 8411result value of the ``add`` is a :ref:`poison value <poisonvalues>` if 8412unsigned and/or signed overflow, respectively, occurs. 8413 8414Example: 8415"""""""" 8416 8417.. code-block:: text 8418 8419 <result> = add i32 4, %var ; yields i32:result = 4 + %var 8420 8421.. _i_fadd: 8422 8423'``fadd``' Instruction 8424^^^^^^^^^^^^^^^^^^^^^^ 8425 8426Syntax: 8427""""""" 8428 8429:: 8430 8431 <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8432 8433Overview: 8434""""""""" 8435 8436The '``fadd``' instruction returns the sum of its two operands. 8437 8438Arguments: 8439"""""""""" 8440 8441The two arguments to the '``fadd``' instruction must be 8442:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8443floating-point values. Both arguments must have identical types. 8444 8445Semantics: 8446"""""""""" 8447 8448The value produced is the floating-point sum of the two operands. 8449This instruction is assumed to execute in the default :ref:`floating-point 8450environment <floatenv>`. 8451This instruction can also take any number of :ref:`fast-math 8452flags <fastmath>`, which are optimization hints to enable otherwise 8453unsafe floating-point optimizations: 8454 8455Example: 8456"""""""" 8457 8458.. code-block:: text 8459 8460 <result> = fadd float 4.0, %var ; yields float:result = 4.0 + %var 8461 8462.. _i_sub: 8463 8464'``sub``' Instruction 8465^^^^^^^^^^^^^^^^^^^^^ 8466 8467Syntax: 8468""""""" 8469 8470:: 8471 8472 <result> = sub <ty> <op1>, <op2> ; yields ty:result 8473 <result> = sub nuw <ty> <op1>, <op2> ; yields ty:result 8474 <result> = sub nsw <ty> <op1>, <op2> ; yields ty:result 8475 <result> = sub nuw nsw <ty> <op1>, <op2> ; yields ty:result 8476 8477Overview: 8478""""""""" 8479 8480The '``sub``' instruction returns the difference of its two operands. 8481 8482Note that the '``sub``' instruction is used to represent the '``neg``' 8483instruction present in most other intermediate representations. 8484 8485Arguments: 8486"""""""""" 8487 8488The two arguments to the '``sub``' instruction must be 8489:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8490arguments must have identical types. 8491 8492Semantics: 8493"""""""""" 8494 8495The value produced is the integer difference of the two operands. 8496 8497If the difference has unsigned overflow, the result returned is the 8498mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of 8499the result. 8500 8501Because LLVM integers use a two's complement representation, this 8502instruction is appropriate for both signed and unsigned integers. 8503 8504``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 8505respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 8506result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if 8507unsigned and/or signed overflow, respectively, occurs. 8508 8509Example: 8510"""""""" 8511 8512.. code-block:: text 8513 8514 <result> = sub i32 4, %var ; yields i32:result = 4 - %var 8515 <result> = sub i32 0, %val ; yields i32:result = -%var 8516 8517.. _i_fsub: 8518 8519'``fsub``' Instruction 8520^^^^^^^^^^^^^^^^^^^^^^ 8521 8522Syntax: 8523""""""" 8524 8525:: 8526 8527 <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8528 8529Overview: 8530""""""""" 8531 8532The '``fsub``' instruction returns the difference of its two operands. 8533 8534Arguments: 8535"""""""""" 8536 8537The two arguments to the '``fsub``' instruction must be 8538:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8539floating-point values. Both arguments must have identical types. 8540 8541Semantics: 8542"""""""""" 8543 8544The value produced is the floating-point difference of the two operands. 8545This instruction is assumed to execute in the default :ref:`floating-point 8546environment <floatenv>`. 8547This instruction can also take any number of :ref:`fast-math 8548flags <fastmath>`, which are optimization hints to enable otherwise 8549unsafe floating-point optimizations: 8550 8551Example: 8552"""""""" 8553 8554.. code-block:: text 8555 8556 <result> = fsub float 4.0, %var ; yields float:result = 4.0 - %var 8557 <result> = fsub float -0.0, %val ; yields float:result = -%var 8558 8559.. _i_mul: 8560 8561'``mul``' Instruction 8562^^^^^^^^^^^^^^^^^^^^^ 8563 8564Syntax: 8565""""""" 8566 8567:: 8568 8569 <result> = mul <ty> <op1>, <op2> ; yields ty:result 8570 <result> = mul nuw <ty> <op1>, <op2> ; yields ty:result 8571 <result> = mul nsw <ty> <op1>, <op2> ; yields ty:result 8572 <result> = mul nuw nsw <ty> <op1>, <op2> ; yields ty:result 8573 8574Overview: 8575""""""""" 8576 8577The '``mul``' instruction returns the product of its two operands. 8578 8579Arguments: 8580"""""""""" 8581 8582The two arguments to the '``mul``' instruction must be 8583:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8584arguments must have identical types. 8585 8586Semantics: 8587"""""""""" 8588 8589The value produced is the integer product of the two operands. 8590 8591If the result of the multiplication has unsigned overflow, the result 8592returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the 8593bit width of the result. 8594 8595Because LLVM integers use a two's complement representation, and the 8596result is the same width as the operands, this instruction returns the 8597correct result for both signed and unsigned integers. If a full product 8598(e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be 8599sign-extended or zero-extended as appropriate to the width of the full 8600product. 8601 8602``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 8603respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 8604result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if 8605unsigned and/or signed overflow, respectively, occurs. 8606 8607Example: 8608"""""""" 8609 8610.. code-block:: text 8611 8612 <result> = mul i32 4, %var ; yields i32:result = 4 * %var 8613 8614.. _i_fmul: 8615 8616'``fmul``' Instruction 8617^^^^^^^^^^^^^^^^^^^^^^ 8618 8619Syntax: 8620""""""" 8621 8622:: 8623 8624 <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8625 8626Overview: 8627""""""""" 8628 8629The '``fmul``' instruction returns the product of its two operands. 8630 8631Arguments: 8632"""""""""" 8633 8634The two arguments to the '``fmul``' instruction must be 8635:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8636floating-point values. Both arguments must have identical types. 8637 8638Semantics: 8639"""""""""" 8640 8641The value produced is the floating-point product of the two operands. 8642This instruction is assumed to execute in the default :ref:`floating-point 8643environment <floatenv>`. 8644This instruction can also take any number of :ref:`fast-math 8645flags <fastmath>`, which are optimization hints to enable otherwise 8646unsafe floating-point optimizations: 8647 8648Example: 8649"""""""" 8650 8651.. code-block:: text 8652 8653 <result> = fmul float 4.0, %var ; yields float:result = 4.0 * %var 8654 8655.. _i_udiv: 8656 8657'``udiv``' Instruction 8658^^^^^^^^^^^^^^^^^^^^^^ 8659 8660Syntax: 8661""""""" 8662 8663:: 8664 8665 <result> = udiv <ty> <op1>, <op2> ; yields ty:result 8666 <result> = udiv exact <ty> <op1>, <op2> ; yields ty:result 8667 8668Overview: 8669""""""""" 8670 8671The '``udiv``' instruction returns the quotient of its two operands. 8672 8673Arguments: 8674"""""""""" 8675 8676The two arguments to the '``udiv``' instruction must be 8677:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8678arguments must have identical types. 8679 8680Semantics: 8681"""""""""" 8682 8683The value produced is the unsigned integer quotient of the two operands. 8684 8685Note that unsigned integer division and signed integer division are 8686distinct operations; for signed integer division, use '``sdiv``'. 8687 8688Division by zero is undefined behavior. For vectors, if any element 8689of the divisor is zero, the operation has undefined behavior. 8690 8691 8692If the ``exact`` keyword is present, the result value of the ``udiv`` is 8693a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as 8694such, "((a udiv exact b) mul b) == a"). 8695 8696Example: 8697"""""""" 8698 8699.. code-block:: text 8700 8701 <result> = udiv i32 4, %var ; yields i32:result = 4 / %var 8702 8703.. _i_sdiv: 8704 8705'``sdiv``' Instruction 8706^^^^^^^^^^^^^^^^^^^^^^ 8707 8708Syntax: 8709""""""" 8710 8711:: 8712 8713 <result> = sdiv <ty> <op1>, <op2> ; yields ty:result 8714 <result> = sdiv exact <ty> <op1>, <op2> ; yields ty:result 8715 8716Overview: 8717""""""""" 8718 8719The '``sdiv``' instruction returns the quotient of its two operands. 8720 8721Arguments: 8722"""""""""" 8723 8724The two arguments to the '``sdiv``' instruction must be 8725:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8726arguments must have identical types. 8727 8728Semantics: 8729"""""""""" 8730 8731The value produced is the signed integer quotient of the two operands 8732rounded towards zero. 8733 8734Note that signed integer division and unsigned integer division are 8735distinct operations; for unsigned integer division, use '``udiv``'. 8736 8737Division by zero is undefined behavior. For vectors, if any element 8738of the divisor is zero, the operation has undefined behavior. 8739Overflow also leads to undefined behavior; this is a rare case, but can 8740occur, for example, by doing a 32-bit division of -2147483648 by -1. 8741 8742If the ``exact`` keyword is present, the result value of the ``sdiv`` is 8743a :ref:`poison value <poisonvalues>` if the result would be rounded. 8744 8745Example: 8746"""""""" 8747 8748.. code-block:: text 8749 8750 <result> = sdiv i32 4, %var ; yields i32:result = 4 / %var 8751 8752.. _i_fdiv: 8753 8754'``fdiv``' Instruction 8755^^^^^^^^^^^^^^^^^^^^^^ 8756 8757Syntax: 8758""""""" 8759 8760:: 8761 8762 <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8763 8764Overview: 8765""""""""" 8766 8767The '``fdiv``' instruction returns the quotient of its two operands. 8768 8769Arguments: 8770"""""""""" 8771 8772The two arguments to the '``fdiv``' instruction must be 8773:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8774floating-point values. Both arguments must have identical types. 8775 8776Semantics: 8777"""""""""" 8778 8779The value produced is the floating-point quotient of the two operands. 8780This instruction is assumed to execute in the default :ref:`floating-point 8781environment <floatenv>`. 8782This instruction can also take any number of :ref:`fast-math 8783flags <fastmath>`, which are optimization hints to enable otherwise 8784unsafe floating-point optimizations: 8785 8786Example: 8787"""""""" 8788 8789.. code-block:: text 8790 8791 <result> = fdiv float 4.0, %var ; yields float:result = 4.0 / %var 8792 8793.. _i_urem: 8794 8795'``urem``' Instruction 8796^^^^^^^^^^^^^^^^^^^^^^ 8797 8798Syntax: 8799""""""" 8800 8801:: 8802 8803 <result> = urem <ty> <op1>, <op2> ; yields ty:result 8804 8805Overview: 8806""""""""" 8807 8808The '``urem``' instruction returns the remainder from the unsigned 8809division of its two arguments. 8810 8811Arguments: 8812"""""""""" 8813 8814The two arguments to the '``urem``' instruction must be 8815:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8816arguments must have identical types. 8817 8818Semantics: 8819"""""""""" 8820 8821This instruction returns the unsigned integer *remainder* of a division. 8822This instruction always performs an unsigned division to get the 8823remainder. 8824 8825Note that unsigned integer remainder and signed integer remainder are 8826distinct operations; for signed integer remainder, use '``srem``'. 8827 8828Taking the remainder of a division by zero is undefined behavior. 8829For vectors, if any element of the divisor is zero, the operation has 8830undefined behavior. 8831 8832Example: 8833"""""""" 8834 8835.. code-block:: text 8836 8837 <result> = urem i32 4, %var ; yields i32:result = 4 % %var 8838 8839.. _i_srem: 8840 8841'``srem``' Instruction 8842^^^^^^^^^^^^^^^^^^^^^^ 8843 8844Syntax: 8845""""""" 8846 8847:: 8848 8849 <result> = srem <ty> <op1>, <op2> ; yields ty:result 8850 8851Overview: 8852""""""""" 8853 8854The '``srem``' instruction returns the remainder from the signed 8855division of its two operands. This instruction can also take 8856:ref:`vector <t_vector>` versions of the values in which case the elements 8857must be integers. 8858 8859Arguments: 8860"""""""""" 8861 8862The two arguments to the '``srem``' instruction must be 8863:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8864arguments must have identical types. 8865 8866Semantics: 8867"""""""""" 8868 8869This instruction returns the *remainder* of a division (where the result 8870is either zero or has the same sign as the dividend, ``op1``), not the 8871*modulo* operator (where the result is either zero or has the same sign 8872as the divisor, ``op2``) of a value. For more information about the 8873difference, see `The Math 8874Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a 8875table of how this is implemented in various languages, please see 8876`Wikipedia: modulo 8877operation <http://en.wikipedia.org/wiki/Modulo_operation>`_. 8878 8879Note that signed integer remainder and unsigned integer remainder are 8880distinct operations; for unsigned integer remainder, use '``urem``'. 8881 8882Taking the remainder of a division by zero is undefined behavior. 8883For vectors, if any element of the divisor is zero, the operation has 8884undefined behavior. 8885Overflow also leads to undefined behavior; this is a rare case, but can 8886occur, for example, by taking the remainder of a 32-bit division of 8887-2147483648 by -1. (The remainder doesn't actually overflow, but this 8888rule lets srem be implemented using instructions that return both the 8889result of the division and the remainder.) 8890 8891Example: 8892"""""""" 8893 8894.. code-block:: text 8895 8896 <result> = srem i32 4, %var ; yields i32:result = 4 % %var 8897 8898.. _i_frem: 8899 8900'``frem``' Instruction 8901^^^^^^^^^^^^^^^^^^^^^^ 8902 8903Syntax: 8904""""""" 8905 8906:: 8907 8908 <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8909 8910Overview: 8911""""""""" 8912 8913The '``frem``' instruction returns the remainder from the division of 8914its two operands. 8915 8916Arguments: 8917"""""""""" 8918 8919The two arguments to the '``frem``' instruction must be 8920:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8921floating-point values. Both arguments must have identical types. 8922 8923Semantics: 8924"""""""""" 8925 8926The value produced is the floating-point remainder of the two operands. 8927This is the same output as a libm '``fmod``' function, but without any 8928possibility of setting ``errno``. The remainder has the same sign as the 8929dividend. 8930This instruction is assumed to execute in the default :ref:`floating-point 8931environment <floatenv>`. 8932This instruction can also take any number of :ref:`fast-math 8933flags <fastmath>`, which are optimization hints to enable otherwise 8934unsafe floating-point optimizations: 8935 8936Example: 8937"""""""" 8938 8939.. code-block:: text 8940 8941 <result> = frem float 4.0, %var ; yields float:result = 4.0 % %var 8942 8943.. _bitwiseops: 8944 8945Bitwise Binary Operations 8946------------------------- 8947 8948Bitwise binary operators are used to do various forms of bit-twiddling 8949in a program. They are generally very efficient instructions and can 8950commonly be strength reduced from other instructions. They require two 8951operands of the same type, execute an operation on them, and produce a 8952single value. The resulting value is the same type as its operands. 8953 8954.. _i_shl: 8955 8956'``shl``' Instruction 8957^^^^^^^^^^^^^^^^^^^^^ 8958 8959Syntax: 8960""""""" 8961 8962:: 8963 8964 <result> = shl <ty> <op1>, <op2> ; yields ty:result 8965 <result> = shl nuw <ty> <op1>, <op2> ; yields ty:result 8966 <result> = shl nsw <ty> <op1>, <op2> ; yields ty:result 8967 <result> = shl nuw nsw <ty> <op1>, <op2> ; yields ty:result 8968 8969Overview: 8970""""""""" 8971 8972The '``shl``' instruction returns the first operand shifted to the left 8973a specified number of bits. 8974 8975Arguments: 8976"""""""""" 8977 8978Both arguments to the '``shl``' instruction must be the same 8979:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 8980'``op2``' is treated as an unsigned value. 8981 8982Semantics: 8983"""""""""" 8984 8985The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`, 8986where ``n`` is the width of the result. If ``op2`` is (statically or 8987dynamically) equal to or larger than the number of bits in 8988``op1``, this instruction returns a :ref:`poison value <poisonvalues>`. 8989If the arguments are vectors, each vector element of ``op1`` is shifted 8990by the corresponding shift amount in ``op2``. 8991 8992If the ``nuw`` keyword is present, then the shift produces a poison 8993value if it shifts out any non-zero bits. 8994If the ``nsw`` keyword is present, then the shift produces a poison 8995value if it shifts out any bits that disagree with the resultant sign bit. 8996 8997Example: 8998"""""""" 8999 9000.. code-block:: text 9001 9002 <result> = shl i32 4, %var ; yields i32: 4 << %var 9003 <result> = shl i32 4, 2 ; yields i32: 16 9004 <result> = shl i32 1, 10 ; yields i32: 1024 9005 <result> = shl i32 1, 32 ; undefined 9006 <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4> 9007 9008.. _i_lshr: 9009 9010 9011'``lshr``' Instruction 9012^^^^^^^^^^^^^^^^^^^^^^ 9013 9014Syntax: 9015""""""" 9016 9017:: 9018 9019 <result> = lshr <ty> <op1>, <op2> ; yields ty:result 9020 <result> = lshr exact <ty> <op1>, <op2> ; yields ty:result 9021 9022Overview: 9023""""""""" 9024 9025The '``lshr``' instruction (logical shift right) returns the first 9026operand shifted to the right a specified number of bits with zero fill. 9027 9028Arguments: 9029"""""""""" 9030 9031Both arguments to the '``lshr``' instruction must be the same 9032:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 9033'``op2``' is treated as an unsigned value. 9034 9035Semantics: 9036"""""""""" 9037 9038This instruction always performs a logical shift right operation. The 9039most significant bits of the result will be filled with zero bits after 9040the shift. If ``op2`` is (statically or dynamically) equal to or larger 9041than the number of bits in ``op1``, this instruction returns a :ref:`poison 9042value <poisonvalues>`. If the arguments are vectors, each vector element 9043of ``op1`` is shifted by the corresponding shift amount in ``op2``. 9044 9045If the ``exact`` keyword is present, the result value of the ``lshr`` is 9046a poison value if any of the bits shifted out are non-zero. 9047 9048Example: 9049"""""""" 9050 9051.. code-block:: text 9052 9053 <result> = lshr i32 4, 1 ; yields i32:result = 2 9054 <result> = lshr i32 4, 2 ; yields i32:result = 1 9055 <result> = lshr i8 4, 3 ; yields i8:result = 0 9056 <result> = lshr i8 -2, 1 ; yields i8:result = 0x7F 9057 <result> = lshr i32 1, 32 ; undefined 9058 <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1> 9059 9060.. _i_ashr: 9061 9062'``ashr``' Instruction 9063^^^^^^^^^^^^^^^^^^^^^^ 9064 9065Syntax: 9066""""""" 9067 9068:: 9069 9070 <result> = ashr <ty> <op1>, <op2> ; yields ty:result 9071 <result> = ashr exact <ty> <op1>, <op2> ; yields ty:result 9072 9073Overview: 9074""""""""" 9075 9076The '``ashr``' instruction (arithmetic shift right) returns the first 9077operand shifted to the right a specified number of bits with sign 9078extension. 9079 9080Arguments: 9081"""""""""" 9082 9083Both arguments to the '``ashr``' instruction must be the same 9084:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 9085'``op2``' is treated as an unsigned value. 9086 9087Semantics: 9088"""""""""" 9089 9090This instruction always performs an arithmetic shift right operation, 9091The most significant bits of the result will be filled with the sign bit 9092of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger 9093than the number of bits in ``op1``, this instruction returns a :ref:`poison 9094value <poisonvalues>`. If the arguments are vectors, each vector element 9095of ``op1`` is shifted by the corresponding shift amount in ``op2``. 9096 9097If the ``exact`` keyword is present, the result value of the ``ashr`` is 9098a poison value if any of the bits shifted out are non-zero. 9099 9100Example: 9101"""""""" 9102 9103.. code-block:: text 9104 9105 <result> = ashr i32 4, 1 ; yields i32:result = 2 9106 <result> = ashr i32 4, 2 ; yields i32:result = 1 9107 <result> = ashr i8 4, 3 ; yields i8:result = 0 9108 <result> = ashr i8 -2, 1 ; yields i8:result = -1 9109 <result> = ashr i32 1, 32 ; undefined 9110 <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0> 9111 9112.. _i_and: 9113 9114'``and``' Instruction 9115^^^^^^^^^^^^^^^^^^^^^ 9116 9117Syntax: 9118""""""" 9119 9120:: 9121 9122 <result> = and <ty> <op1>, <op2> ; yields ty:result 9123 9124Overview: 9125""""""""" 9126 9127The '``and``' instruction returns the bitwise logical and of its two 9128operands. 9129 9130Arguments: 9131"""""""""" 9132 9133The two arguments to the '``and``' instruction must be 9134:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9135arguments must have identical types. 9136 9137Semantics: 9138"""""""""" 9139 9140The truth table used for the '``and``' instruction is: 9141 9142+-----+-----+-----+ 9143| In0 | In1 | Out | 9144+-----+-----+-----+ 9145| 0 | 0 | 0 | 9146+-----+-----+-----+ 9147| 0 | 1 | 0 | 9148+-----+-----+-----+ 9149| 1 | 0 | 0 | 9150+-----+-----+-----+ 9151| 1 | 1 | 1 | 9152+-----+-----+-----+ 9153 9154Example: 9155"""""""" 9156 9157.. code-block:: text 9158 9159 <result> = and i32 4, %var ; yields i32:result = 4 & %var 9160 <result> = and i32 15, 40 ; yields i32:result = 8 9161 <result> = and i32 4, 8 ; yields i32:result = 0 9162 9163.. _i_or: 9164 9165'``or``' Instruction 9166^^^^^^^^^^^^^^^^^^^^ 9167 9168Syntax: 9169""""""" 9170 9171:: 9172 9173 <result> = or <ty> <op1>, <op2> ; yields ty:result 9174 9175Overview: 9176""""""""" 9177 9178The '``or``' instruction returns the bitwise logical inclusive or of its 9179two operands. 9180 9181Arguments: 9182"""""""""" 9183 9184The two arguments to the '``or``' instruction must be 9185:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9186arguments must have identical types. 9187 9188Semantics: 9189"""""""""" 9190 9191The truth table used for the '``or``' instruction is: 9192 9193+-----+-----+-----+ 9194| In0 | In1 | Out | 9195+-----+-----+-----+ 9196| 0 | 0 | 0 | 9197+-----+-----+-----+ 9198| 0 | 1 | 1 | 9199+-----+-----+-----+ 9200| 1 | 0 | 1 | 9201+-----+-----+-----+ 9202| 1 | 1 | 1 | 9203+-----+-----+-----+ 9204 9205Example: 9206"""""""" 9207 9208:: 9209 9210 <result> = or i32 4, %var ; yields i32:result = 4 | %var 9211 <result> = or i32 15, 40 ; yields i32:result = 47 9212 <result> = or i32 4, 8 ; yields i32:result = 12 9213 9214.. _i_xor: 9215 9216'``xor``' Instruction 9217^^^^^^^^^^^^^^^^^^^^^ 9218 9219Syntax: 9220""""""" 9221 9222:: 9223 9224 <result> = xor <ty> <op1>, <op2> ; yields ty:result 9225 9226Overview: 9227""""""""" 9228 9229The '``xor``' instruction returns the bitwise logical exclusive or of 9230its two operands. The ``xor`` is used to implement the "one's 9231complement" operation, which is the "~" operator in C. 9232 9233Arguments: 9234"""""""""" 9235 9236The two arguments to the '``xor``' instruction must be 9237:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9238arguments must have identical types. 9239 9240Semantics: 9241"""""""""" 9242 9243The truth table used for the '``xor``' instruction is: 9244 9245+-----+-----+-----+ 9246| In0 | In1 | Out | 9247+-----+-----+-----+ 9248| 0 | 0 | 0 | 9249+-----+-----+-----+ 9250| 0 | 1 | 1 | 9251+-----+-----+-----+ 9252| 1 | 0 | 1 | 9253+-----+-----+-----+ 9254| 1 | 1 | 0 | 9255+-----+-----+-----+ 9256 9257Example: 9258"""""""" 9259 9260.. code-block:: text 9261 9262 <result> = xor i32 4, %var ; yields i32:result = 4 ^ %var 9263 <result> = xor i32 15, 40 ; yields i32:result = 39 9264 <result> = xor i32 4, 8 ; yields i32:result = 12 9265 <result> = xor i32 %V, -1 ; yields i32:result = ~%V 9266 9267Vector Operations 9268----------------- 9269 9270LLVM supports several instructions to represent vector operations in a 9271target-independent manner. These instructions cover the element-access 9272and vector-specific operations needed to process vectors effectively. 9273While LLVM does directly support these vector operations, many 9274sophisticated algorithms will want to use target-specific intrinsics to 9275take full advantage of a specific target. 9276 9277.. _i_extractelement: 9278 9279'``extractelement``' Instruction 9280^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9281 9282Syntax: 9283""""""" 9284 9285:: 9286 9287 <result> = extractelement <n x <ty>> <val>, <ty2> <idx> ; yields <ty> 9288 <result> = extractelement <vscale x n x <ty>> <val>, <ty2> <idx> ; yields <ty> 9289 9290Overview: 9291""""""""" 9292 9293The '``extractelement``' instruction extracts a single scalar element 9294from a vector at a specified index. 9295 9296Arguments: 9297"""""""""" 9298 9299The first operand of an '``extractelement``' instruction is a value of 9300:ref:`vector <t_vector>` type. The second operand is an index indicating 9301the position from which to extract the element. The index may be a 9302variable of any integer type. 9303 9304Semantics: 9305"""""""""" 9306 9307The result is a scalar of the same type as the element type of ``val``. 9308Its value is the value at position ``idx`` of ``val``. If ``idx`` 9309exceeds the length of ``val`` for a fixed-length vector, the result is a 9310:ref:`poison value <poisonvalues>`. For a scalable vector, if the value 9311of ``idx`` exceeds the runtime length of the vector, the result is a 9312:ref:`poison value <poisonvalues>`. 9313 9314Example: 9315"""""""" 9316 9317.. code-block:: text 9318 9319 <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32 9320 9321.. _i_insertelement: 9322 9323'``insertelement``' Instruction 9324^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9325 9326Syntax: 9327""""""" 9328 9329:: 9330 9331 <result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <n x <ty>> 9332 <result> = insertelement <vscale x n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <vscale x n x <ty>> 9333 9334Overview: 9335""""""""" 9336 9337The '``insertelement``' instruction inserts a scalar element into a 9338vector at a specified index. 9339 9340Arguments: 9341"""""""""" 9342 9343The first operand of an '``insertelement``' instruction is a value of 9344:ref:`vector <t_vector>` type. The second operand is a scalar value whose 9345type must equal the element type of the first operand. The third operand 9346is an index indicating the position at which to insert the value. The 9347index may be a variable of any integer type. 9348 9349Semantics: 9350"""""""""" 9351 9352The result is a vector of the same type as ``val``. Its element values 9353are those of ``val`` except at position ``idx``, where it gets the value 9354``elt``. If ``idx`` exceeds the length of ``val`` for a fixed-length vector, 9355the result is a :ref:`poison value <poisonvalues>`. For a scalable vector, 9356if the value of ``idx`` exceeds the runtime length of the vector, the result 9357is a :ref:`poison value <poisonvalues>`. 9358 9359Example: 9360"""""""" 9361 9362.. code-block:: text 9363 9364 <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32> 9365 9366.. _i_shufflevector: 9367 9368'``shufflevector``' Instruction 9369^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9370 9371Syntax: 9372""""""" 9373 9374:: 9375 9376 <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>> 9377 <result> = shufflevector <vscale x n x <ty>> <v1>, <vscale x n x <ty>> v2, <vscale x m x i32> <mask> ; yields <vscale x m x <ty>> 9378 9379Overview: 9380""""""""" 9381 9382The '``shufflevector``' instruction constructs a permutation of elements 9383from two input vectors, returning a vector with the same element type as 9384the input and length that is the same as the shuffle mask. 9385 9386Arguments: 9387"""""""""" 9388 9389The first two operands of a '``shufflevector``' instruction are vectors 9390with the same type. The third argument is a shuffle mask vector constant 9391whose element type is ``i32``. The mask vector elements must be constant 9392integers or ``undef`` values. The result of the instruction is a vector 9393whose length is the same as the shuffle mask and whose element type is the 9394same as the element type of the first two operands. 9395 9396Semantics: 9397"""""""""" 9398 9399The elements of the two input vectors are numbered from left to right 9400across both of the vectors. For each element of the result vector, the 9401shuffle mask selects an element from one of the input vectors to copy 9402to the result. Non-negative elements in the mask represent an index 9403into the concatenated pair of input vectors. 9404 9405If the shuffle mask is undefined, the result vector is undefined. If 9406the shuffle mask selects an undefined element from one of the input 9407vectors, the resulting element is undefined. An undefined element 9408in the mask vector specifies that the resulting element is undefined. 9409An undefined element in the mask vector prevents a poisoned vector 9410element from propagating. 9411 9412For scalable vectors, the only valid mask values at present are 9413``zeroinitializer`` and ``undef``, since we cannot write all indices as 9414literals for a vector with a length unknown at compile time. 9415 9416Example: 9417"""""""" 9418 9419.. code-block:: text 9420 9421 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 9422 <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32> 9423 <result> = shufflevector <4 x i32> %v1, <4 x i32> undef, 9424 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle. 9425 <result> = shufflevector <8 x i32> %v1, <8 x i32> undef, 9426 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> 9427 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 9428 <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32> 9429 9430Aggregate Operations 9431-------------------- 9432 9433LLVM supports several instructions for working with 9434:ref:`aggregate <t_aggregate>` values. 9435 9436.. _i_extractvalue: 9437 9438'``extractvalue``' Instruction 9439^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9440 9441Syntax: 9442""""""" 9443 9444:: 9445 9446 <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}* 9447 9448Overview: 9449""""""""" 9450 9451The '``extractvalue``' instruction extracts the value of a member field 9452from an :ref:`aggregate <t_aggregate>` value. 9453 9454Arguments: 9455"""""""""" 9456 9457The first operand of an '``extractvalue``' instruction is a value of 9458:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The other operands are 9459constant indices to specify which value to extract in a similar manner 9460as indices in a '``getelementptr``' instruction. 9461 9462The major differences to ``getelementptr`` indexing are: 9463 9464- Since the value being indexed is not a pointer, the first index is 9465 omitted and assumed to be zero. 9466- At least one index must be specified. 9467- Not only struct indices but also array indices must be in bounds. 9468 9469Semantics: 9470"""""""""" 9471 9472The result is the value at the position in the aggregate specified by 9473the index operands. 9474 9475Example: 9476"""""""" 9477 9478.. code-block:: text 9479 9480 <result> = extractvalue {i32, float} %agg, 0 ; yields i32 9481 9482.. _i_insertvalue: 9483 9484'``insertvalue``' Instruction 9485^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9486 9487Syntax: 9488""""""" 9489 9490:: 9491 9492 <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type> 9493 9494Overview: 9495""""""""" 9496 9497The '``insertvalue``' instruction inserts a value into a member field in 9498an :ref:`aggregate <t_aggregate>` value. 9499 9500Arguments: 9501"""""""""" 9502 9503The first operand of an '``insertvalue``' instruction is a value of 9504:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The second operand is 9505a first-class value to insert. The following operands are constant 9506indices indicating the position at which to insert the value in a 9507similar manner as indices in a '``extractvalue``' instruction. The value 9508to insert must have the same type as the value identified by the 9509indices. 9510 9511Semantics: 9512"""""""""" 9513 9514The result is an aggregate of the same type as ``val``. Its value is 9515that of ``val`` except that the value at the position specified by the 9516indices is that of ``elt``. 9517 9518Example: 9519"""""""" 9520 9521.. code-block:: llvm 9522 9523 %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef} 9524 %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val} 9525 %agg3 = insertvalue {i32, {float}} undef, float %val, 1, 0 ; yields {i32 undef, {float %val}} 9526 9527.. _memoryops: 9528 9529Memory Access and Addressing Operations 9530--------------------------------------- 9531 9532A key design point of an SSA-based representation is how it represents 9533memory. In LLVM, no memory locations are in SSA form, which makes things 9534very simple. This section describes how to read, write, and allocate 9535memory in LLVM. 9536 9537.. _i_alloca: 9538 9539'``alloca``' Instruction 9540^^^^^^^^^^^^^^^^^^^^^^^^ 9541 9542Syntax: 9543""""""" 9544 9545:: 9546 9547 <result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] [, addrspace(<num>)] ; yields type addrspace(num)*:result 9548 9549Overview: 9550""""""""" 9551 9552The '``alloca``' instruction allocates memory on the stack frame of the 9553currently executing function, to be automatically released when this 9554function returns to its caller. The object is always allocated in the 9555address space for allocas indicated in the datalayout. 9556 9557Arguments: 9558"""""""""" 9559 9560The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements`` 9561bytes of memory on the runtime stack, returning a pointer of the 9562appropriate type to the program. If "NumElements" is specified, it is 9563the number of elements allocated, otherwise "NumElements" is defaulted 9564to be one. If a constant alignment is specified, the value result of the 9565allocation is guaranteed to be aligned to at least that boundary. The 9566alignment may not be greater than ``1 << 29``. If not specified, or if 9567zero, the target can choose to align the allocation on any convenient 9568boundary compatible with the type. 9569 9570'``type``' may be any sized type. 9571 9572Semantics: 9573"""""""""" 9574 9575Memory is allocated; a pointer is returned. The allocated memory is 9576uninitialized, and loading from uninitialized memory produces an undefined 9577value. The operation itself is undefined if there is insufficient stack 9578space for the allocation.'``alloca``'d memory is automatically released 9579when the function returns. The '``alloca``' instruction is commonly used 9580to represent automatic variables that must have an address available. When 9581the function returns (either with the ``ret`` or ``resume`` instructions), 9582the memory is reclaimed. Allocating zero bytes is legal, but the returned 9583pointer may not be unique. The order in which memory is allocated (ie., 9584which way the stack grows) is not specified. 9585 9586If the returned pointer is used by :ref:`llvm.lifetime.start <int_lifestart>`, 9587the returned object is initially dead. 9588See :ref:`llvm.lifetime.start <int_lifestart>` and 9589:ref:`llvm.lifetime.end <int_lifeend>` for the precise semantics of 9590lifetime-manipulating intrinsics. 9591 9592Example: 9593"""""""" 9594 9595.. code-block:: llvm 9596 9597 %ptr = alloca i32 ; yields i32*:ptr 9598 %ptr = alloca i32, i32 4 ; yields i32*:ptr 9599 %ptr = alloca i32, i32 4, align 1024 ; yields i32*:ptr 9600 %ptr = alloca i32, align 1024 ; yields i32*:ptr 9601 9602.. _i_load: 9603 9604'``load``' Instruction 9605^^^^^^^^^^^^^^^^^^^^^^ 9606 9607Syntax: 9608""""""" 9609 9610:: 9611 9612 <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<nontemp_node>][, !invariant.load !<empty_node>][, !invariant.group !<empty_node>][, !nonnull !<empty_node>][, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !align !<align_node>][, !noundef !<empty_node>] 9613 <result> = load atomic [volatile] <ty>, <ty>* <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>] 9614 !<nontemp_node> = !{ i32 1 } 9615 !<empty_node> = !{} 9616 !<deref_bytes_node> = !{ i64 <dereferenceable_bytes> } 9617 !<align_node> = !{ i64 <value_alignment> } 9618 9619Overview: 9620""""""""" 9621 9622The '``load``' instruction is used to read from memory. 9623 9624Arguments: 9625"""""""""" 9626 9627The argument to the ``load`` instruction specifies the memory address from which 9628to load. The type specified must be a :ref:`first class <t_firstclass>` type of 9629known size (i.e. not containing an :ref:`opaque structural type <t_opaque>`). If 9630the ``load`` is marked as ``volatile``, then the optimizer is not allowed to 9631modify the number or order of execution of this ``load`` with other 9632:ref:`volatile operations <volatile>`. 9633 9634If the ``load`` is marked as ``atomic``, it takes an extra :ref:`ordering 9635<ordering>` and optional ``syncscope("<target-scope>")`` argument. The 9636``release`` and ``acq_rel`` orderings are not valid on ``load`` instructions. 9637Atomic loads produce :ref:`defined <memmodel>` results when they may see 9638multiple atomic stores. The type of the pointee must be an integer, pointer, or 9639floating-point type whose bit width is a power of two greater than or equal to 9640eight and less than or equal to a target-specific size limit. ``align`` must be 9641explicitly specified on atomic loads, and the load has undefined behavior if the 9642alignment is not set to a value which is at least the size in bytes of the 9643pointee. ``!nontemporal`` does not have any defined semantics for atomic loads. 9644 9645The optional constant ``align`` argument specifies the alignment of the 9646operation (that is, the alignment of the memory address). A value of 0 9647or an omitted ``align`` argument means that the operation has the ABI 9648alignment for the target. It is the responsibility of the code emitter 9649to ensure that the alignment information is correct. Overestimating the 9650alignment results in undefined behavior. Underestimating the alignment 9651may produce less efficient code. An alignment of 1 is always safe. The 9652maximum possible alignment is ``1 << 29``. An alignment value higher 9653than the size of the loaded type implies memory up to the alignment 9654value bytes can be safely loaded without trapping in the default 9655address space. Access of the high bytes can interfere with debugging 9656tools, so should not be accessed if the function has the 9657``sanitize_thread`` or ``sanitize_address`` attributes. 9658 9659The optional ``!nontemporal`` metadata must reference a single 9660metadata name ``<nontemp_node>`` corresponding to a metadata node with one 9661``i32`` entry of value 1. The existence of the ``!nontemporal`` 9662metadata on the instruction tells the optimizer and code generator 9663that this load is not expected to be reused in the cache. The code 9664generator may select special instructions to save cache bandwidth, such 9665as the ``MOVNT`` instruction on x86. 9666 9667The optional ``!invariant.load`` metadata must reference a single 9668metadata name ``<empty_node>`` corresponding to a metadata node with no 9669entries. If a load instruction tagged with the ``!invariant.load`` 9670metadata is executed, the memory location referenced by the load has 9671to contain the same value at all points in the program where the 9672memory location is dereferenceable; otherwise, the behavior is 9673undefined. 9674 9675The optional ``!invariant.group`` metadata must reference a single metadata name 9676 ``<empty_node>`` corresponding to a metadata node with no entries. 9677 See ``invariant.group`` metadata :ref:`invariant.group <md_invariant.group>`. 9678 9679The optional ``!nonnull`` metadata must reference a single 9680metadata name ``<empty_node>`` corresponding to a metadata node with no 9681entries. The existence of the ``!nonnull`` metadata on the 9682instruction tells the optimizer that the value loaded is known to 9683never be null. If the value is null at runtime, the behavior is undefined. 9684This is analogous to the ``nonnull`` attribute on parameters and return 9685values. This metadata can only be applied to loads of a pointer type. 9686 9687The optional ``!dereferenceable`` metadata must reference a single metadata 9688name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64`` 9689entry. 9690See ``dereferenceable`` metadata :ref:`dereferenceable <md_dereferenceable>`. 9691 9692The optional ``!dereferenceable_or_null`` metadata must reference a single 9693metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one 9694``i64`` entry. 9695See ``dereferenceable_or_null`` metadata :ref:`dereferenceable_or_null 9696<md_dereferenceable_or_null>`. 9697 9698The optional ``!align`` metadata must reference a single metadata name 9699``<align_node>`` corresponding to a metadata node with one ``i64`` entry. 9700The existence of the ``!align`` metadata on the instruction tells the 9701optimizer that the value loaded is known to be aligned to a boundary specified 9702by the integer value in the metadata node. The alignment must be a power of 2. 9703This is analogous to the ''align'' attribute on parameters and return values. 9704This metadata can only be applied to loads of a pointer type. If the returned 9705value is not appropriately aligned at runtime, the behavior is undefined. 9706 9707The optional ``!noundef`` metadata must reference a single metadata name 9708``<empty_node>`` corresponding to a node with no entries. The existence of 9709``!noundef`` metadata on the instruction tells the optimizer that the value 9710loaded is known to be :ref:`well defined <welldefinedvalues>`. 9711If the value isn't well defined, the behavior is undefined. 9712 9713Semantics: 9714"""""""""" 9715 9716The location of memory pointed to is loaded. If the value being loaded 9717is of scalar type then the number of bytes read does not exceed the 9718minimum number of bytes needed to hold all bits of the type. For 9719example, loading an ``i24`` reads at most three bytes. When loading a 9720value of a type like ``i20`` with a size that is not an integral number 9721of bytes, the result is undefined if the value was not originally 9722written using a store of the same type. 9723If the value being loaded is of aggregate type, the bytes that correspond to 9724padding may be accessed but are ignored, because it is impossible to observe 9725padding from the loaded aggregate value. 9726If ``<pointer>`` is not a well-defined value, the behavior is undefined. 9727 9728Examples: 9729""""""""" 9730 9731.. code-block:: llvm 9732 9733 %ptr = alloca i32 ; yields i32*:ptr 9734 store i32 3, i32* %ptr ; yields void 9735 %val = load i32, i32* %ptr ; yields i32:val = i32 3 9736 9737.. _i_store: 9738 9739'``store``' Instruction 9740^^^^^^^^^^^^^^^^^^^^^^^ 9741 9742Syntax: 9743""""""" 9744 9745:: 9746 9747 store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<nontemp_node>][, !invariant.group !<empty_node>] ; yields void 9748 store atomic [volatile] <ty> <value>, <ty>* <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>] ; yields void 9749 !<nontemp_node> = !{ i32 1 } 9750 !<empty_node> = !{} 9751 9752Overview: 9753""""""""" 9754 9755The '``store``' instruction is used to write to memory. 9756 9757Arguments: 9758"""""""""" 9759 9760There are two arguments to the ``store`` instruction: a value to store and an 9761address at which to store it. The type of the ``<pointer>`` operand must be a 9762pointer to the :ref:`first class <t_firstclass>` type of the ``<value>`` 9763operand. If the ``store`` is marked as ``volatile``, then the optimizer is not 9764allowed to modify the number or order of execution of this ``store`` with other 9765:ref:`volatile operations <volatile>`. Only values of :ref:`first class 9766<t_firstclass>` types of known size (i.e. not containing an :ref:`opaque 9767structural type <t_opaque>`) can be stored. 9768 9769If the ``store`` is marked as ``atomic``, it takes an extra :ref:`ordering 9770<ordering>` and optional ``syncscope("<target-scope>")`` argument. The 9771``acquire`` and ``acq_rel`` orderings aren't valid on ``store`` instructions. 9772Atomic loads produce :ref:`defined <memmodel>` results when they may see 9773multiple atomic stores. The type of the pointee must be an integer, pointer, or 9774floating-point type whose bit width is a power of two greater than or equal to 9775eight and less than or equal to a target-specific size limit. ``align`` must be 9776explicitly specified on atomic stores, and the store has undefined behavior if 9777the alignment is not set to a value which is at least the size in bytes of the 9778pointee. ``!nontemporal`` does not have any defined semantics for atomic stores. 9779 9780The optional constant ``align`` argument specifies the alignment of the 9781operation (that is, the alignment of the memory address). A value of 0 9782or an omitted ``align`` argument means that the operation has the ABI 9783alignment for the target. It is the responsibility of the code emitter 9784to ensure that the alignment information is correct. Overestimating the 9785alignment results in undefined behavior. Underestimating the 9786alignment may produce less efficient code. An alignment of 1 is always 9787safe. The maximum possible alignment is ``1 << 29``. An alignment 9788value higher than the size of the stored type implies memory up to the 9789alignment value bytes can be stored to without trapping in the default 9790address space. Storing to the higher bytes however may result in data 9791races if another thread can access the same address. Introducing a 9792data race is not allowed. Storing to the extra bytes is not allowed 9793even in situations where a data race is known to not exist if the 9794function has the ``sanitize_address`` attribute. 9795 9796The optional ``!nontemporal`` metadata must reference a single metadata 9797name ``<nontemp_node>`` corresponding to a metadata node with one ``i32`` entry 9798of value 1. The existence of the ``!nontemporal`` metadata on the instruction 9799tells the optimizer and code generator that this load is not expected to 9800be reused in the cache. The code generator may select special 9801instructions to save cache bandwidth, such as the ``MOVNT`` instruction on 9802x86. 9803 9804The optional ``!invariant.group`` metadata must reference a 9805single metadata name ``<empty_node>``. See ``invariant.group`` metadata. 9806 9807Semantics: 9808"""""""""" 9809 9810The contents of memory are updated to contain ``<value>`` at the 9811location specified by the ``<pointer>`` operand. If ``<value>`` is 9812of scalar type then the number of bytes written does not exceed the 9813minimum number of bytes needed to hold all bits of the type. For 9814example, storing an ``i24`` writes at most three bytes. When writing a 9815value of a type like ``i20`` with a size that is not an integral number 9816of bytes, it is unspecified what happens to the extra bits that do not 9817belong to the type, but they will typically be overwritten. 9818If ``<value>`` is of aggregate type, padding is filled with 9819:ref:`undef <undefvalues>`. 9820If ``<pointer>`` is not a well-defined value, the behavior is undefined. 9821 9822Example: 9823"""""""" 9824 9825.. code-block:: llvm 9826 9827 %ptr = alloca i32 ; yields i32*:ptr 9828 store i32 3, i32* %ptr ; yields void 9829 %val = load i32, i32* %ptr ; yields i32:val = i32 3 9830 9831.. _i_fence: 9832 9833'``fence``' Instruction 9834^^^^^^^^^^^^^^^^^^^^^^^ 9835 9836Syntax: 9837""""""" 9838 9839:: 9840 9841 fence [syncscope("<target-scope>")] <ordering> ; yields void 9842 9843Overview: 9844""""""""" 9845 9846The '``fence``' instruction is used to introduce happens-before edges 9847between operations. 9848 9849Arguments: 9850"""""""""" 9851 9852'``fence``' instructions take an :ref:`ordering <ordering>` argument which 9853defines what *synchronizes-with* edges they add. They can only be given 9854``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings. 9855 9856Semantics: 9857"""""""""" 9858 9859A fence A which has (at least) ``release`` ordering semantics 9860*synchronizes with* a fence B with (at least) ``acquire`` ordering 9861semantics if and only if there exist atomic operations X and Y, both 9862operating on some atomic object M, such that A is sequenced before X, X 9863modifies M (either directly or through some side effect of a sequence 9864headed by X), Y is sequenced before B, and Y observes M. This provides a 9865*happens-before* dependency between A and B. Rather than an explicit 9866``fence``, one (but not both) of the atomic operations X or Y might 9867provide a ``release`` or ``acquire`` (resp.) ordering constraint and 9868still *synchronize-with* the explicit ``fence`` and establish the 9869*happens-before* edge. 9870 9871A ``fence`` which has ``seq_cst`` ordering, in addition to having both 9872``acquire`` and ``release`` semantics specified above, participates in 9873the global program order of other ``seq_cst`` operations and/or fences. 9874 9875A ``fence`` instruction can also take an optional 9876":ref:`syncscope <syncscope>`" argument. 9877 9878Example: 9879"""""""" 9880 9881.. code-block:: text 9882 9883 fence acquire ; yields void 9884 fence syncscope("singlethread") seq_cst ; yields void 9885 fence syncscope("agent") seq_cst ; yields void 9886 9887.. _i_cmpxchg: 9888 9889'``cmpxchg``' Instruction 9890^^^^^^^^^^^^^^^^^^^^^^^^^ 9891 9892Syntax: 9893""""""" 9894 9895:: 9896 9897 cmpxchg [weak] [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [syncscope("<target-scope>")] <success ordering> <failure ordering>[, align <alignment>] ; yields { ty, i1 } 9898 9899Overview: 9900""""""""" 9901 9902The '``cmpxchg``' instruction is used to atomically modify memory. It 9903loads a value in memory and compares it to a given value. If they are 9904equal, it tries to store a new value into the memory. 9905 9906Arguments: 9907"""""""""" 9908 9909There are three arguments to the '``cmpxchg``' instruction: an address 9910to operate on, a value to compare to the value currently be at that 9911address, and a new value to place at that address if the compared values 9912are equal. The type of '<cmp>' must be an integer or pointer type whose 9913bit width is a power of two greater than or equal to eight and less 9914than or equal to a target-specific size limit. '<cmp>' and '<new>' must 9915have the same type, and the type of '<pointer>' must be a pointer to 9916that type. If the ``cmpxchg`` is marked as ``volatile``, then the 9917optimizer is not allowed to modify the number or order of execution of 9918this ``cmpxchg`` with other :ref:`volatile operations <volatile>`. 9919 9920The success and failure :ref:`ordering <ordering>` arguments specify how this 9921``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters 9922must be at least ``monotonic``, the failure ordering cannot be either 9923``release`` or ``acq_rel``. 9924 9925A ``cmpxchg`` instruction can also take an optional 9926":ref:`syncscope <syncscope>`" argument. 9927 9928The instruction can take an optional ``align`` attribute. 9929The alignment must be a power of two greater or equal to the size of the 9930`<value>` type. If unspecified, the alignment is assumed to be equal to the 9931size of the '<value>' type. Note that this default alignment assumption is 9932different from the alignment used for the load/store instructions when align 9933isn't specified. 9934 9935The pointer passed into cmpxchg must have alignment greater than or 9936equal to the size in memory of the operand. 9937 9938Semantics: 9939"""""""""" 9940 9941The contents of memory at the location specified by the '``<pointer>``' operand 9942is read and compared to '``<cmp>``'; if the values are equal, '``<new>``' is 9943written to the location. The original value at the location is returned, 9944together with a flag indicating success (true) or failure (false). 9945 9946If the cmpxchg operation is marked as ``weak`` then a spurious failure is 9947permitted: the operation may not write ``<new>`` even if the comparison 9948matched. 9949 9950If the cmpxchg operation is strong (the default), the i1 value is 1 if and only 9951if the value loaded equals ``cmp``. 9952 9953A successful ``cmpxchg`` is a read-modify-write instruction for the purpose of 9954identifying release sequences. A failed ``cmpxchg`` is equivalent to an atomic 9955load with an ordering parameter determined the second ordering parameter. 9956 9957Example: 9958"""""""" 9959 9960.. code-block:: llvm 9961 9962 entry: 9963 %orig = load atomic i32, i32* %ptr unordered, align 4 ; yields i32 9964 br label %loop 9965 9966 loop: 9967 %cmp = phi i32 [ %orig, %entry ], [%value_loaded, %loop] 9968 %squared = mul i32 %cmp, %cmp 9969 %val_success = cmpxchg i32* %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields { i32, i1 } 9970 %value_loaded = extractvalue { i32, i1 } %val_success, 0 9971 %success = extractvalue { i32, i1 } %val_success, 1 9972 br i1 %success, label %done, label %loop 9973 9974 done: 9975 ... 9976 9977.. _i_atomicrmw: 9978 9979'``atomicrmw``' Instruction 9980^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9981 9982Syntax: 9983""""""" 9984 9985:: 9986 9987 atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [syncscope("<target-scope>")] <ordering>[, align <alignment>] ; yields ty 9988 9989Overview: 9990""""""""" 9991 9992The '``atomicrmw``' instruction is used to atomically modify memory. 9993 9994Arguments: 9995"""""""""" 9996 9997There are three arguments to the '``atomicrmw``' instruction: an 9998operation to apply, an address whose value to modify, an argument to the 9999operation. The operation must be one of the following keywords: 10000 10001- xchg 10002- add 10003- sub 10004- and 10005- nand 10006- or 10007- xor 10008- max 10009- min 10010- umax 10011- umin 10012- fadd 10013- fsub 10014 10015For most of these operations, the type of '<value>' must be an integer 10016type whose bit width is a power of two greater than or equal to eight 10017and less than or equal to a target-specific size limit. For xchg, this 10018may also be a floating point type with the same size constraints as 10019integers. For fadd/fsub, this must be a floating point type. The 10020type of the '``<pointer>``' operand must be a pointer to that type. If 10021the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not 10022allowed to modify the number or order of execution of this 10023``atomicrmw`` with other :ref:`volatile operations <volatile>`. 10024 10025The instruction can take an optional ``align`` attribute. 10026The alignment must be a power of two greater or equal to the size of the 10027`<value>` type. If unspecified, the alignment is assumed to be equal to the 10028size of the '<value>' type. Note that this default alignment assumption is 10029different from the alignment used for the load/store instructions when align 10030isn't specified. 10031 10032A ``atomicrmw`` instruction can also take an optional 10033":ref:`syncscope <syncscope>`" argument. 10034 10035Semantics: 10036"""""""""" 10037 10038The contents of memory at the location specified by the '``<pointer>``' 10039operand are atomically read, modified, and written back. The original 10040value at the location is returned. The modification is specified by the 10041operation argument: 10042 10043- xchg: ``*ptr = val`` 10044- add: ``*ptr = *ptr + val`` 10045- sub: ``*ptr = *ptr - val`` 10046- and: ``*ptr = *ptr & val`` 10047- nand: ``*ptr = ~(*ptr & val)`` 10048- or: ``*ptr = *ptr | val`` 10049- xor: ``*ptr = *ptr ^ val`` 10050- max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison) 10051- min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison) 10052- umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned comparison) 10053- umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned comparison) 10054- fadd: ``*ptr = *ptr + val`` (using floating point arithmetic) 10055- fsub: ``*ptr = *ptr - val`` (using floating point arithmetic) 10056 10057Example: 10058"""""""" 10059 10060.. code-block:: llvm 10061 10062 %old = atomicrmw add i32* %ptr, i32 1 acquire ; yields i32 10063 10064.. _i_getelementptr: 10065 10066'``getelementptr``' Instruction 10067^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10068 10069Syntax: 10070""""""" 10071 10072:: 10073 10074 <result> = getelementptr <ty>, <ty>* <ptrval>{, [inrange] <ty> <idx>}* 10075 <result> = getelementptr inbounds <ty>, <ty>* <ptrval>{, [inrange] <ty> <idx>}* 10076 <result> = getelementptr <ty>, <ptr vector> <ptrval>, [inrange] <vector index type> <idx> 10077 10078Overview: 10079""""""""" 10080 10081The '``getelementptr``' instruction is used to get the address of a 10082subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs 10083address calculation only and does not access memory. The instruction can also 10084be used to calculate a vector of such addresses. 10085 10086Arguments: 10087"""""""""" 10088 10089The first argument is always a type used as the basis for the calculations. 10090The second argument is always a pointer or a vector of pointers, and is the 10091base address to start from. The remaining arguments are indices 10092that indicate which of the elements of the aggregate object are indexed. 10093The interpretation of each index is dependent on the type being indexed 10094into. The first index always indexes the pointer value given as the 10095second argument, the second index indexes a value of the type pointed to 10096(not necessarily the value directly pointed to, since the first index 10097can be non-zero), etc. The first type indexed into must be a pointer 10098value, subsequent types can be arrays, vectors, and structs. Note that 10099subsequent types being indexed into can never be pointers, since that 10100would require loading the pointer before continuing calculation. 10101 10102The type of each index argument depends on the type it is indexing into. 10103When indexing into a (optionally packed) structure, only ``i32`` integer 10104**constants** are allowed (when using a vector of indices they must all 10105be the **same** ``i32`` integer constant). When indexing into an array, 10106pointer or vector, integers of any width are allowed, and they are not 10107required to be constant. These integers are treated as signed values 10108where relevant. 10109 10110For example, let's consider a C code fragment and how it gets compiled 10111to LLVM: 10112 10113.. code-block:: c 10114 10115 struct RT { 10116 char A; 10117 int B[10][20]; 10118 char C; 10119 }; 10120 struct ST { 10121 int X; 10122 double Y; 10123 struct RT Z; 10124 }; 10125 10126 int *foo(struct ST *s) { 10127 return &s[1].Z.B[5][13]; 10128 } 10129 10130The LLVM code generated by Clang is: 10131 10132.. code-block:: llvm 10133 10134 %struct.RT = type { i8, [10 x [20 x i32]], i8 } 10135 %struct.ST = type { i32, double, %struct.RT } 10136 10137 define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp { 10138 entry: 10139 %arrayidx = getelementptr inbounds %struct.ST, %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13 10140 ret i32* %arrayidx 10141 } 10142 10143Semantics: 10144"""""""""" 10145 10146In the example above, the first index is indexing into the 10147'``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``' 10148= '``{ i32, double, %struct.RT }``' type, a structure. The second index 10149indexes into the third element of the structure, yielding a 10150'``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another 10151structure. The third index indexes into the second element of the 10152structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two 10153dimensions of the array are subscripted into, yielding an '``i32``' 10154type. The '``getelementptr``' instruction returns a pointer to this 10155element, thus computing a value of '``i32*``' type. 10156 10157Note that it is perfectly legal to index partially through a structure, 10158returning a pointer to an inner element. Because of this, the LLVM code 10159for the given testcase is equivalent to: 10160 10161.. code-block:: llvm 10162 10163 define i32* @foo(%struct.ST* %s) { 10164 %t1 = getelementptr %struct.ST, %struct.ST* %s, i32 1 ; yields %struct.ST*:%t1 10165 %t2 = getelementptr %struct.ST, %struct.ST* %t1, i32 0, i32 2 ; yields %struct.RT*:%t2 10166 %t3 = getelementptr %struct.RT, %struct.RT* %t2, i32 0, i32 1 ; yields [10 x [20 x i32]]*:%t3 10167 %t4 = getelementptr [10 x [20 x i32]], [10 x [20 x i32]]* %t3, i32 0, i32 5 ; yields [20 x i32]*:%t4 10168 %t5 = getelementptr [20 x i32], [20 x i32]* %t4, i32 0, i32 13 ; yields i32*:%t5 10169 ret i32* %t5 10170 } 10171 10172If the ``inbounds`` keyword is present, the result value of the 10173``getelementptr`` is a :ref:`poison value <poisonvalues>` if one of the 10174following rules is violated: 10175 10176* The base pointer has an *in bounds* address of an allocated object, which 10177 means that it points into an allocated object, or to its end. The only 10178 *in bounds* address for a null pointer in the default address-space is the 10179 null pointer itself. 10180* If the type of an index is larger than the pointer index type, the 10181 truncation to the pointer index type preserves the signed value. 10182* The multiplication of an index by the type size does not wrap the pointer 10183 index type in a signed sense (``nsw``). 10184* The successive addition of offsets (without adding the base address) does 10185 not wrap the pointer index type in a signed sense (``nsw``). 10186* The successive addition of the current address, interpreted as an unsigned 10187 number, and an offset, interpreted as a signed number, does not wrap the 10188 unsigned address space and remains *in bounds* of the allocated object. 10189 As a corollary, if the added offset is non-negative, the addition does not 10190 wrap in an unsigned sense (``nuw``). 10191* In cases where the base is a vector of pointers, the ``inbounds`` keyword 10192 applies to each of the computations element-wise. 10193 10194These rules are based on the assumption that no allocated object may cross 10195the unsigned address space boundary, and no allocated object may be larger 10196than half the pointer index type space. 10197 10198If the ``inbounds`` keyword is not present, the offsets are added to the 10199base address with silently-wrapping two's complement arithmetic. If the 10200offsets have a different width from the pointer, they are sign-extended 10201or truncated to the width of the pointer. The result value of the 10202``getelementptr`` may be outside the object pointed to by the base 10203pointer. The result value may not necessarily be used to access memory 10204though, even if it happens to point into allocated storage. See the 10205:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more 10206information. 10207 10208If the ``inrange`` keyword is present before any index, loading from or 10209storing to any pointer derived from the ``getelementptr`` has undefined 10210behavior if the load or store would access memory outside of the bounds of 10211the element selected by the index marked as ``inrange``. The result of a 10212pointer comparison or ``ptrtoint`` (including ``ptrtoint``-like operations 10213involving memory) involving a pointer derived from a ``getelementptr`` with 10214the ``inrange`` keyword is undefined, with the exception of comparisons 10215in the case where both operands are in the range of the element selected 10216by the ``inrange`` keyword, inclusive of the address one past the end of 10217that element. Note that the ``inrange`` keyword is currently only allowed 10218in constant ``getelementptr`` expressions. 10219 10220The getelementptr instruction is often confusing. For some more insight 10221into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`. 10222 10223Example: 10224"""""""" 10225 10226.. code-block:: llvm 10227 10228 ; yields [12 x i8]*:aptr 10229 %aptr = getelementptr {i32, [12 x i8]}, {i32, [12 x i8]}* %saptr, i64 0, i32 1 10230 ; yields i8*:vptr 10231 %vptr = getelementptr {i32, <2 x i8>}, {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1 10232 ; yields i8*:eptr 10233 %eptr = getelementptr [12 x i8], [12 x i8]* %aptr, i64 0, i32 1 10234 ; yields i32*:iptr 10235 %iptr = getelementptr [10 x i32], [10 x i32]* @arr, i16 0, i16 0 10236 10237Vector of pointers: 10238""""""""""""""""""" 10239 10240The ``getelementptr`` returns a vector of pointers, instead of a single address, 10241when one or more of its arguments is a vector. In such cases, all vector 10242arguments should have the same number of elements, and every scalar argument 10243will be effectively broadcast into a vector during address calculation. 10244 10245.. code-block:: llvm 10246 10247 ; All arguments are vectors: 10248 ; A[i] = ptrs[i] + offsets[i]*sizeof(i8) 10249 %A = getelementptr i8, <4 x i8*> %ptrs, <4 x i64> %offsets 10250 10251 ; Add the same scalar offset to each pointer of a vector: 10252 ; A[i] = ptrs[i] + offset*sizeof(i8) 10253 %A = getelementptr i8, <4 x i8*> %ptrs, i64 %offset 10254 10255 ; Add distinct offsets to the same pointer: 10256 ; A[i] = ptr + offsets[i]*sizeof(i8) 10257 %A = getelementptr i8, i8* %ptr, <4 x i64> %offsets 10258 10259 ; In all cases described above the type of the result is <4 x i8*> 10260 10261The two following instructions are equivalent: 10262 10263.. code-block:: llvm 10264 10265 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1, 10266 <4 x i32> <i32 2, i32 2, i32 2, i32 2>, 10267 <4 x i32> <i32 1, i32 1, i32 1, i32 1>, 10268 <4 x i32> %ind4, 10269 <4 x i64> <i64 13, i64 13, i64 13, i64 13> 10270 10271 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1, 10272 i32 2, i32 1, <4 x i32> %ind4, i64 13 10273 10274Let's look at the C code, where the vector version of ``getelementptr`` 10275makes sense: 10276 10277.. code-block:: c 10278 10279 // Let's assume that we vectorize the following loop: 10280 double *A, *B; int *C; 10281 for (int i = 0; i < size; ++i) { 10282 A[i] = B[C[i]]; 10283 } 10284 10285.. code-block:: llvm 10286 10287 ; get pointers for 8 elements from array B 10288 %ptrs = getelementptr double, double* %B, <8 x i32> %C 10289 ; load 8 elements from array B into A 10290 %A = call <8 x double> @llvm.masked.gather.v8f64.v8p0f64(<8 x double*> %ptrs, 10291 i32 8, <8 x i1> %mask, <8 x double> %passthru) 10292 10293Conversion Operations 10294--------------------- 10295 10296The instructions in this category are the conversion instructions 10297(casting) which all take a single operand and a type. They perform 10298various bit conversions on the operand. 10299 10300.. _i_trunc: 10301 10302'``trunc .. to``' Instruction 10303^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10304 10305Syntax: 10306""""""" 10307 10308:: 10309 10310 <result> = trunc <ty> <value> to <ty2> ; yields ty2 10311 10312Overview: 10313""""""""" 10314 10315The '``trunc``' instruction truncates its operand to the type ``ty2``. 10316 10317Arguments: 10318"""""""""" 10319 10320The '``trunc``' instruction takes a value to trunc, and a type to trunc 10321it to. Both types must be of :ref:`integer <t_integer>` types, or vectors 10322of the same number of integers. The bit size of the ``value`` must be 10323larger than the bit size of the destination type, ``ty2``. Equal sized 10324types are not allowed. 10325 10326Semantics: 10327"""""""""" 10328 10329The '``trunc``' instruction truncates the high order bits in ``value`` 10330and converts the remaining bits to ``ty2``. Since the source size must 10331be larger than the destination size, ``trunc`` cannot be a *no-op cast*. 10332It will always truncate bits. 10333 10334Example: 10335"""""""" 10336 10337.. code-block:: llvm 10338 10339 %X = trunc i32 257 to i8 ; yields i8:1 10340 %Y = trunc i32 123 to i1 ; yields i1:true 10341 %Z = trunc i32 122 to i1 ; yields i1:false 10342 %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7> 10343 10344.. _i_zext: 10345 10346'``zext .. to``' Instruction 10347^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10348 10349Syntax: 10350""""""" 10351 10352:: 10353 10354 <result> = zext <ty> <value> to <ty2> ; yields ty2 10355 10356Overview: 10357""""""""" 10358 10359The '``zext``' instruction zero extends its operand to type ``ty2``. 10360 10361Arguments: 10362"""""""""" 10363 10364The '``zext``' instruction takes a value to cast, and a type to cast it 10365to. Both types must be of :ref:`integer <t_integer>` types, or vectors of 10366the same number of integers. The bit size of the ``value`` must be 10367smaller than the bit size of the destination type, ``ty2``. 10368 10369Semantics: 10370"""""""""" 10371 10372The ``zext`` fills the high order bits of the ``value`` with zero bits 10373until it reaches the size of the destination type, ``ty2``. 10374 10375When zero extending from i1, the result will always be either 0 or 1. 10376 10377Example: 10378"""""""" 10379 10380.. code-block:: llvm 10381 10382 %X = zext i32 257 to i64 ; yields i64:257 10383 %Y = zext i1 true to i32 ; yields i32:1 10384 %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> 10385 10386.. _i_sext: 10387 10388'``sext .. to``' Instruction 10389^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10390 10391Syntax: 10392""""""" 10393 10394:: 10395 10396 <result> = sext <ty> <value> to <ty2> ; yields ty2 10397 10398Overview: 10399""""""""" 10400 10401The '``sext``' sign extends ``value`` to the type ``ty2``. 10402 10403Arguments: 10404"""""""""" 10405 10406The '``sext``' instruction takes a value to cast, and a type to cast it 10407to. Both types must be of :ref:`integer <t_integer>` types, or vectors of 10408the same number of integers. The bit size of the ``value`` must be 10409smaller than the bit size of the destination type, ``ty2``. 10410 10411Semantics: 10412"""""""""" 10413 10414The '``sext``' instruction performs a sign extension by copying the sign 10415bit (highest order bit) of the ``value`` until it reaches the bit size 10416of the type ``ty2``. 10417 10418When sign extending from i1, the extension always results in -1 or 0. 10419 10420Example: 10421"""""""" 10422 10423.. code-block:: llvm 10424 10425 %X = sext i8 -1 to i16 ; yields i16 :65535 10426 %Y = sext i1 true to i32 ; yields i32:-1 10427 %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> 10428 10429'``fptrunc .. to``' Instruction 10430^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10431 10432Syntax: 10433""""""" 10434 10435:: 10436 10437 <result> = fptrunc <ty> <value> to <ty2> ; yields ty2 10438 10439Overview: 10440""""""""" 10441 10442The '``fptrunc``' instruction truncates ``value`` to type ``ty2``. 10443 10444Arguments: 10445"""""""""" 10446 10447The '``fptrunc``' instruction takes a :ref:`floating-point <t_floating>` 10448value to cast and a :ref:`floating-point <t_floating>` type to cast it to. 10449The size of ``value`` must be larger than the size of ``ty2``. This 10450implies that ``fptrunc`` cannot be used to make a *no-op cast*. 10451 10452Semantics: 10453"""""""""" 10454 10455The '``fptrunc``' instruction casts a ``value`` from a larger 10456:ref:`floating-point <t_floating>` type to a smaller :ref:`floating-point 10457<t_floating>` type. 10458This instruction is assumed to execute in the default :ref:`floating-point 10459environment <floatenv>`. 10460 10461Example: 10462"""""""" 10463 10464.. code-block:: llvm 10465 10466 %X = fptrunc double 16777217.0 to float ; yields float:16777216.0 10467 %Y = fptrunc double 1.0E+300 to half ; yields half:+infinity 10468 10469'``fpext .. to``' Instruction 10470^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10471 10472Syntax: 10473""""""" 10474 10475:: 10476 10477 <result> = fpext <ty> <value> to <ty2> ; yields ty2 10478 10479Overview: 10480""""""""" 10481 10482The '``fpext``' extends a floating-point ``value`` to a larger floating-point 10483value. 10484 10485Arguments: 10486"""""""""" 10487 10488The '``fpext``' instruction takes a :ref:`floating-point <t_floating>` 10489``value`` to cast, and a :ref:`floating-point <t_floating>` type to cast it 10490to. The source type must be smaller than the destination type. 10491 10492Semantics: 10493"""""""""" 10494 10495The '``fpext``' instruction extends the ``value`` from a smaller 10496:ref:`floating-point <t_floating>` type to a larger :ref:`floating-point 10497<t_floating>` type. The ``fpext`` cannot be used to make a 10498*no-op cast* because it always changes bits. Use ``bitcast`` to make a 10499*no-op cast* for a floating-point cast. 10500 10501Example: 10502"""""""" 10503 10504.. code-block:: llvm 10505 10506 %X = fpext float 3.125 to double ; yields double:3.125000e+00 10507 %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000 10508 10509'``fptoui .. to``' Instruction 10510^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10511 10512Syntax: 10513""""""" 10514 10515:: 10516 10517 <result> = fptoui <ty> <value> to <ty2> ; yields ty2 10518 10519Overview: 10520""""""""" 10521 10522The '``fptoui``' converts a floating-point ``value`` to its unsigned 10523integer equivalent of type ``ty2``. 10524 10525Arguments: 10526"""""""""" 10527 10528The '``fptoui``' instruction takes a value to cast, which must be a 10529scalar or vector :ref:`floating-point <t_floating>` value, and a type to 10530cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If 10531``ty`` is a vector floating-point type, ``ty2`` must be a vector integer 10532type with the same number of elements as ``ty`` 10533 10534Semantics: 10535"""""""""" 10536 10537The '``fptoui``' instruction converts its :ref:`floating-point 10538<t_floating>` operand into the nearest (rounding towards zero) 10539unsigned integer value. If the value cannot fit in ``ty2``, the result 10540is a :ref:`poison value <poisonvalues>`. 10541 10542Example: 10543"""""""" 10544 10545.. code-block:: llvm 10546 10547 %X = fptoui double 123.0 to i32 ; yields i32:123 10548 %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1 10549 %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1 10550 10551'``fptosi .. to``' Instruction 10552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10553 10554Syntax: 10555""""""" 10556 10557:: 10558 10559 <result> = fptosi <ty> <value> to <ty2> ; yields ty2 10560 10561Overview: 10562""""""""" 10563 10564The '``fptosi``' instruction converts :ref:`floating-point <t_floating>` 10565``value`` to type ``ty2``. 10566 10567Arguments: 10568"""""""""" 10569 10570The '``fptosi``' instruction takes a value to cast, which must be a 10571scalar or vector :ref:`floating-point <t_floating>` value, and a type to 10572cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If 10573``ty`` is a vector floating-point type, ``ty2`` must be a vector integer 10574type with the same number of elements as ``ty`` 10575 10576Semantics: 10577"""""""""" 10578 10579The '``fptosi``' instruction converts its :ref:`floating-point 10580<t_floating>` operand into the nearest (rounding towards zero) 10581signed integer value. If the value cannot fit in ``ty2``, the result 10582is a :ref:`poison value <poisonvalues>`. 10583 10584Example: 10585"""""""" 10586 10587.. code-block:: llvm 10588 10589 %X = fptosi double -123.0 to i32 ; yields i32:-123 10590 %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1 10591 %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1 10592 10593'``uitofp .. to``' Instruction 10594^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10595 10596Syntax: 10597""""""" 10598 10599:: 10600 10601 <result> = uitofp <ty> <value> to <ty2> ; yields ty2 10602 10603Overview: 10604""""""""" 10605 10606The '``uitofp``' instruction regards ``value`` as an unsigned integer 10607and converts that value to the ``ty2`` type. 10608 10609Arguments: 10610"""""""""" 10611 10612The '``uitofp``' instruction takes a value to cast, which must be a 10613scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to 10614``ty2``, which must be an :ref:`floating-point <t_floating>` type. If 10615``ty`` is a vector integer type, ``ty2`` must be a vector floating-point 10616type with the same number of elements as ``ty`` 10617 10618Semantics: 10619"""""""""" 10620 10621The '``uitofp``' instruction interprets its operand as an unsigned 10622integer quantity and converts it to the corresponding floating-point 10623value. If the value cannot be exactly represented, it is rounded using 10624the default rounding mode. 10625 10626 10627Example: 10628"""""""" 10629 10630.. code-block:: llvm 10631 10632 %X = uitofp i32 257 to float ; yields float:257.0 10633 %Y = uitofp i8 -1 to double ; yields double:255.0 10634 10635'``sitofp .. to``' Instruction 10636^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10637 10638Syntax: 10639""""""" 10640 10641:: 10642 10643 <result> = sitofp <ty> <value> to <ty2> ; yields ty2 10644 10645Overview: 10646""""""""" 10647 10648The '``sitofp``' instruction regards ``value`` as a signed integer and 10649converts that value to the ``ty2`` type. 10650 10651Arguments: 10652"""""""""" 10653 10654The '``sitofp``' instruction takes a value to cast, which must be a 10655scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to 10656``ty2``, which must be an :ref:`floating-point <t_floating>` type. If 10657``ty`` is a vector integer type, ``ty2`` must be a vector floating-point 10658type with the same number of elements as ``ty`` 10659 10660Semantics: 10661"""""""""" 10662 10663The '``sitofp``' instruction interprets its operand as a signed integer 10664quantity and converts it to the corresponding floating-point value. If the 10665value cannot be exactly represented, it is rounded using the default rounding 10666mode. 10667 10668Example: 10669"""""""" 10670 10671.. code-block:: llvm 10672 10673 %X = sitofp i32 257 to float ; yields float:257.0 10674 %Y = sitofp i8 -1 to double ; yields double:-1.0 10675 10676.. _i_ptrtoint: 10677 10678'``ptrtoint .. to``' Instruction 10679^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10680 10681Syntax: 10682""""""" 10683 10684:: 10685 10686 <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2 10687 10688Overview: 10689""""""""" 10690 10691The '``ptrtoint``' instruction converts the pointer or a vector of 10692pointers ``value`` to the integer (or vector of integers) type ``ty2``. 10693 10694Arguments: 10695"""""""""" 10696 10697The '``ptrtoint``' instruction takes a ``value`` to cast, which must be 10698a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a 10699type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or 10700a vector of integers type. 10701 10702Semantics: 10703"""""""""" 10704 10705The '``ptrtoint``' instruction converts ``value`` to integer type 10706``ty2`` by interpreting the pointer value as an integer and either 10707truncating or zero extending that value to the size of the integer type. 10708If ``value`` is smaller than ``ty2`` then a zero extension is done. If 10709``value`` is larger than ``ty2`` then a truncation is done. If they are 10710the same size, then nothing is done (*no-op cast*) other than a type 10711change. 10712 10713Example: 10714"""""""" 10715 10716.. code-block:: llvm 10717 10718 %X = ptrtoint i32* %P to i8 ; yields truncation on 32-bit architecture 10719 %Y = ptrtoint i32* %P to i64 ; yields zero extension on 32-bit architecture 10720 %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture 10721 10722.. _i_inttoptr: 10723 10724'``inttoptr .. to``' Instruction 10725^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10726 10727Syntax: 10728""""""" 10729 10730:: 10731 10732 <result> = inttoptr <ty> <value> to <ty2>[, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>] ; yields ty2 10733 10734Overview: 10735""""""""" 10736 10737The '``inttoptr``' instruction converts an integer ``value`` to a 10738pointer type, ``ty2``. 10739 10740Arguments: 10741"""""""""" 10742 10743The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to 10744cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>` 10745type. 10746 10747The optional ``!dereferenceable`` metadata must reference a single metadata 10748name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64`` 10749entry. 10750See ``dereferenceable`` metadata. 10751 10752The optional ``!dereferenceable_or_null`` metadata must reference a single 10753metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one 10754``i64`` entry. 10755See ``dereferenceable_or_null`` metadata. 10756 10757Semantics: 10758"""""""""" 10759 10760The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by 10761applying either a zero extension or a truncation depending on the size 10762of the integer ``value``. If ``value`` is larger than the size of a 10763pointer then a truncation is done. If ``value`` is smaller than the size 10764of a pointer then a zero extension is done. If they are the same size, 10765nothing is done (*no-op cast*). 10766 10767Example: 10768"""""""" 10769 10770.. code-block:: llvm 10771 10772 %X = inttoptr i32 255 to i32* ; yields zero extension on 64-bit architecture 10773 %Y = inttoptr i32 255 to i32* ; yields no-op on 32-bit architecture 10774 %Z = inttoptr i64 0 to i32* ; yields truncation on 32-bit architecture 10775 %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers 10776 10777.. _i_bitcast: 10778 10779'``bitcast .. to``' Instruction 10780^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10781 10782Syntax: 10783""""""" 10784 10785:: 10786 10787 <result> = bitcast <ty> <value> to <ty2> ; yields ty2 10788 10789Overview: 10790""""""""" 10791 10792The '``bitcast``' instruction converts ``value`` to type ``ty2`` without 10793changing any bits. 10794 10795Arguments: 10796"""""""""" 10797 10798The '``bitcast``' instruction takes a value to cast, which must be a 10799non-aggregate first class value, and a type to cast it to, which must 10800also be a non-aggregate :ref:`first class <t_firstclass>` type. The 10801bit sizes of ``value`` and the destination type, ``ty2``, must be 10802identical. If the source type is a pointer, the destination type must 10803also be a pointer of the same size. This instruction supports bitwise 10804conversion of vectors to integers and to vectors of other types (as 10805long as they have the same size). 10806 10807Semantics: 10808"""""""""" 10809 10810The '``bitcast``' instruction converts ``value`` to type ``ty2``. It 10811is always a *no-op cast* because no bits change with this 10812conversion. The conversion is done as if the ``value`` had been stored 10813to memory and read back as type ``ty2``. Pointer (or vector of 10814pointers) types may only be converted to other pointer (or vector of 10815pointers) types with the same address space through this instruction. 10816To convert pointers to other types, use the :ref:`inttoptr <i_inttoptr>` 10817or :ref:`ptrtoint <i_ptrtoint>` instructions first. 10818 10819There is a caveat for bitcasts involving vector types in relation to 10820endianess. For example ``bitcast <2 x i8> <value> to i16`` puts element zero 10821of the vector in the least significant bits of the i16 for little-endian while 10822element zero ends up in the most significant bits for big-endian. 10823 10824Example: 10825"""""""" 10826 10827.. code-block:: text 10828 10829 %X = bitcast i8 255 to i8 ; yields i8 :-1 10830 %Y = bitcast i32* %x to sint* ; yields sint*:%x 10831 %Z = bitcast <2 x int> %V to i64; ; yields i64: %V (depends on endianess) 10832 %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*> 10833 10834.. _i_addrspacecast: 10835 10836'``addrspacecast .. to``' Instruction 10837^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10838 10839Syntax: 10840""""""" 10841 10842:: 10843 10844 <result> = addrspacecast <pty> <ptrval> to <pty2> ; yields pty2 10845 10846Overview: 10847""""""""" 10848 10849The '``addrspacecast``' instruction converts ``ptrval`` from ``pty`` in 10850address space ``n`` to type ``pty2`` in address space ``m``. 10851 10852Arguments: 10853"""""""""" 10854 10855The '``addrspacecast``' instruction takes a pointer or vector of pointer value 10856to cast and a pointer type to cast it to, which must have a different 10857address space. 10858 10859Semantics: 10860"""""""""" 10861 10862The '``addrspacecast``' instruction converts the pointer value 10863``ptrval`` to type ``pty2``. It can be a *no-op cast* or a complex 10864value modification, depending on the target and the address space 10865pair. Pointer conversions within the same address space must be 10866performed with the ``bitcast`` instruction. Note that if the address space 10867conversion is legal then both result and operand refer to the same memory 10868location. 10869 10870Example: 10871"""""""" 10872 10873.. code-block:: llvm 10874 10875 %X = addrspacecast i32* %x to i32 addrspace(1)* ; yields i32 addrspace(1)*:%x 10876 %Y = addrspacecast i32 addrspace(1)* %y to i64 addrspace(2)* ; yields i64 addrspace(2)*:%y 10877 %Z = addrspacecast <4 x i32*> %z to <4 x float addrspace(3)*> ; yields <4 x float addrspace(3)*>:%z 10878 10879.. _otherops: 10880 10881Other Operations 10882---------------- 10883 10884The instructions in this category are the "miscellaneous" instructions, 10885which defy better classification. 10886 10887.. _i_icmp: 10888 10889'``icmp``' Instruction 10890^^^^^^^^^^^^^^^^^^^^^^ 10891 10892Syntax: 10893""""""" 10894 10895:: 10896 10897 <result> = icmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result 10898 10899Overview: 10900""""""""" 10901 10902The '``icmp``' instruction returns a boolean value or a vector of 10903boolean values based on comparison of its two integer, integer vector, 10904pointer, or pointer vector operands. 10905 10906Arguments: 10907"""""""""" 10908 10909The '``icmp``' instruction takes three operands. The first operand is 10910the condition code indicating the kind of comparison to perform. It is 10911not a value, just a keyword. The possible condition codes are: 10912 10913#. ``eq``: equal 10914#. ``ne``: not equal 10915#. ``ugt``: unsigned greater than 10916#. ``uge``: unsigned greater or equal 10917#. ``ult``: unsigned less than 10918#. ``ule``: unsigned less or equal 10919#. ``sgt``: signed greater than 10920#. ``sge``: signed greater or equal 10921#. ``slt``: signed less than 10922#. ``sle``: signed less or equal 10923 10924The remaining two arguments must be :ref:`integer <t_integer>` or 10925:ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They 10926must also be identical types. 10927 10928Semantics: 10929"""""""""" 10930 10931The '``icmp``' compares ``op1`` and ``op2`` according to the condition 10932code given as ``cond``. The comparison performed always yields either an 10933:ref:`i1 <t_integer>` or vector of ``i1`` result, as follows: 10934 10935#. ``eq``: yields ``true`` if the operands are equal, ``false`` 10936 otherwise. No sign interpretation is necessary or performed. 10937#. ``ne``: yields ``true`` if the operands are unequal, ``false`` 10938 otherwise. No sign interpretation is necessary or performed. 10939#. ``ugt``: interprets the operands as unsigned values and yields 10940 ``true`` if ``op1`` is greater than ``op2``. 10941#. ``uge``: interprets the operands as unsigned values and yields 10942 ``true`` if ``op1`` is greater than or equal to ``op2``. 10943#. ``ult``: interprets the operands as unsigned values and yields 10944 ``true`` if ``op1`` is less than ``op2``. 10945#. ``ule``: interprets the operands as unsigned values and yields 10946 ``true`` if ``op1`` is less than or equal to ``op2``. 10947#. ``sgt``: interprets the operands as signed values and yields ``true`` 10948 if ``op1`` is greater than ``op2``. 10949#. ``sge``: interprets the operands as signed values and yields ``true`` 10950 if ``op1`` is greater than or equal to ``op2``. 10951#. ``slt``: interprets the operands as signed values and yields ``true`` 10952 if ``op1`` is less than ``op2``. 10953#. ``sle``: interprets the operands as signed values and yields ``true`` 10954 if ``op1`` is less than or equal to ``op2``. 10955 10956If the operands are :ref:`pointer <t_pointer>` typed, the pointer values 10957are compared as if they were integers. 10958 10959If the operands are integer vectors, then they are compared element by 10960element. The result is an ``i1`` vector with the same number of elements 10961as the values being compared. Otherwise, the result is an ``i1``. 10962 10963Example: 10964"""""""" 10965 10966.. code-block:: text 10967 10968 <result> = icmp eq i32 4, 5 ; yields: result=false 10969 <result> = icmp ne float* %X, %X ; yields: result=false 10970 <result> = icmp ult i16 4, 5 ; yields: result=true 10971 <result> = icmp sgt i16 4, 5 ; yields: result=false 10972 <result> = icmp ule i16 -4, 5 ; yields: result=false 10973 <result> = icmp sge i16 4, 5 ; yields: result=false 10974 10975.. _i_fcmp: 10976 10977'``fcmp``' Instruction 10978^^^^^^^^^^^^^^^^^^^^^^ 10979 10980Syntax: 10981""""""" 10982 10983:: 10984 10985 <result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result 10986 10987Overview: 10988""""""""" 10989 10990The '``fcmp``' instruction returns a boolean value or vector of boolean 10991values based on comparison of its operands. 10992 10993If the operands are floating-point scalars, then the result type is a 10994boolean (:ref:`i1 <t_integer>`). 10995 10996If the operands are floating-point vectors, then the result type is a 10997vector of boolean with the same number of elements as the operands being 10998compared. 10999 11000Arguments: 11001"""""""""" 11002 11003The '``fcmp``' instruction takes three operands. The first operand is 11004the condition code indicating the kind of comparison to perform. It is 11005not a value, just a keyword. The possible condition codes are: 11006 11007#. ``false``: no comparison, always returns false 11008#. ``oeq``: ordered and equal 11009#. ``ogt``: ordered and greater than 11010#. ``oge``: ordered and greater than or equal 11011#. ``olt``: ordered and less than 11012#. ``ole``: ordered and less than or equal 11013#. ``one``: ordered and not equal 11014#. ``ord``: ordered (no nans) 11015#. ``ueq``: unordered or equal 11016#. ``ugt``: unordered or greater than 11017#. ``uge``: unordered or greater than or equal 11018#. ``ult``: unordered or less than 11019#. ``ule``: unordered or less than or equal 11020#. ``une``: unordered or not equal 11021#. ``uno``: unordered (either nans) 11022#. ``true``: no comparison, always returns true 11023 11024*Ordered* means that neither operand is a QNAN while *unordered* means 11025that either operand may be a QNAN. 11026 11027Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating-point 11028<t_floating>` type or a :ref:`vector <t_vector>` of floating-point type. 11029They must have identical types. 11030 11031Semantics: 11032"""""""""" 11033 11034The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the 11035condition code given as ``cond``. If the operands are vectors, then the 11036vectors are compared element by element. Each comparison performed 11037always yields an :ref:`i1 <t_integer>` result, as follows: 11038 11039#. ``false``: always yields ``false``, regardless of operands. 11040#. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1`` 11041 is equal to ``op2``. 11042#. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1`` 11043 is greater than ``op2``. 11044#. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1`` 11045 is greater than or equal to ``op2``. 11046#. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1`` 11047 is less than ``op2``. 11048#. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1`` 11049 is less than or equal to ``op2``. 11050#. ``one``: yields ``true`` if both operands are not a QNAN and ``op1`` 11051 is not equal to ``op2``. 11052#. ``ord``: yields ``true`` if both operands are not a QNAN. 11053#. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is 11054 equal to ``op2``. 11055#. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is 11056 greater than ``op2``. 11057#. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is 11058 greater than or equal to ``op2``. 11059#. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is 11060 less than ``op2``. 11061#. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is 11062 less than or equal to ``op2``. 11063#. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is 11064 not equal to ``op2``. 11065#. ``uno``: yields ``true`` if either operand is a QNAN. 11066#. ``true``: always yields ``true``, regardless of operands. 11067 11068The ``fcmp`` instruction can also optionally take any number of 11069:ref:`fast-math flags <fastmath>`, which are optimization hints to enable 11070otherwise unsafe floating-point optimizations. 11071 11072Any set of fast-math flags are legal on an ``fcmp`` instruction, but the 11073only flags that have any effect on its semantics are those that allow 11074assumptions to be made about the values of input arguments; namely 11075``nnan``, ``ninf``, and ``reassoc``. See :ref:`fastmath` for more information. 11076 11077Example: 11078"""""""" 11079 11080.. code-block:: text 11081 11082 <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false 11083 <result> = fcmp one float 4.0, 5.0 ; yields: result=true 11084 <result> = fcmp olt float 4.0, 5.0 ; yields: result=true 11085 <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false 11086 11087.. _i_phi: 11088 11089'``phi``' Instruction 11090^^^^^^^^^^^^^^^^^^^^^ 11091 11092Syntax: 11093""""""" 11094 11095:: 11096 11097 <result> = phi [fast-math-flags] <ty> [ <val0>, <label0>], ... 11098 11099Overview: 11100""""""""" 11101 11102The '``phi``' instruction is used to implement the φ node in the SSA 11103graph representing the function. 11104 11105Arguments: 11106"""""""""" 11107 11108The type of the incoming values is specified with the first type field. 11109After this, the '``phi``' instruction takes a list of pairs as 11110arguments, with one pair for each predecessor basic block of the current 11111block. Only values of :ref:`first class <t_firstclass>` type may be used as 11112the value arguments to the PHI node. Only labels may be used as the 11113label arguments. 11114 11115There must be no non-phi instructions between the start of a basic block 11116and the PHI instructions: i.e. PHI instructions must be first in a basic 11117block. 11118 11119For the purposes of the SSA form, the use of each incoming value is 11120deemed to occur on the edge from the corresponding predecessor block to 11121the current block (but after any definition of an '``invoke``' 11122instruction's return value on the same edge). 11123 11124The optional ``fast-math-flags`` marker indicates that the phi has one 11125or more :ref:`fast-math-flags <fastmath>`. These are optimization hints 11126to enable otherwise unsafe floating-point optimizations. Fast-math-flags 11127are only valid for phis that return a floating-point scalar or vector 11128type, or an array (nested to any depth) of floating-point scalar or vector 11129types. 11130 11131Semantics: 11132"""""""""" 11133 11134At runtime, the '``phi``' instruction logically takes on the value 11135specified by the pair corresponding to the predecessor basic block that 11136executed just prior to the current block. 11137 11138Example: 11139"""""""" 11140 11141.. code-block:: llvm 11142 11143 Loop: ; Infinite loop that counts from 0 on up... 11144 %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ] 11145 %nextindvar = add i32 %indvar, 1 11146 br label %Loop 11147 11148.. _i_select: 11149 11150'``select``' Instruction 11151^^^^^^^^^^^^^^^^^^^^^^^^ 11152 11153Syntax: 11154""""""" 11155 11156:: 11157 11158 <result> = select [fast-math flags] selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty 11159 11160 selty is either i1 or {<N x i1>} 11161 11162Overview: 11163""""""""" 11164 11165The '``select``' instruction is used to choose one value based on a 11166condition, without IR-level branching. 11167 11168Arguments: 11169"""""""""" 11170 11171The '``select``' instruction requires an 'i1' value or a vector of 'i1' 11172values indicating the condition, and two values of the same :ref:`first 11173class <t_firstclass>` type. 11174 11175#. The optional ``fast-math flags`` marker indicates that the select has one or more 11176 :ref:`fast-math flags <fastmath>`. These are optimization hints to enable 11177 otherwise unsafe floating-point optimizations. Fast-math flags are only valid 11178 for selects that return a floating-point scalar or vector type, or an array 11179 (nested to any depth) of floating-point scalar or vector types. 11180 11181Semantics: 11182"""""""""" 11183 11184If the condition is an i1 and it evaluates to 1, the instruction returns 11185the first value argument; otherwise, it returns the second value 11186argument. 11187 11188If the condition is a vector of i1, then the value arguments must be 11189vectors of the same size, and the selection is done element by element. 11190 11191If the condition is an i1 and the value arguments are vectors of the 11192same size, then an entire vector is selected. 11193 11194Example: 11195"""""""" 11196 11197.. code-block:: llvm 11198 11199 %X = select i1 true, i8 17, i8 42 ; yields i8:17 11200 11201 11202.. _i_freeze: 11203 11204'``freeze``' Instruction 11205^^^^^^^^^^^^^^^^^^^^^^^^ 11206 11207Syntax: 11208""""""" 11209 11210:: 11211 11212 <result> = freeze ty <val> ; yields ty:result 11213 11214Overview: 11215""""""""" 11216 11217The '``freeze``' instruction is used to stop propagation of 11218:ref:`undef <undefvalues>` and :ref:`poison <poisonvalues>` values. 11219 11220Arguments: 11221"""""""""" 11222 11223The '``freeze``' instruction takes a single argument. 11224 11225Semantics: 11226"""""""""" 11227 11228If the argument is ``undef`` or ``poison``, '``freeze``' returns an 11229arbitrary, but fixed, value of type '``ty``'. 11230Otherwise, this instruction is a no-op and returns the input argument. 11231All uses of a value returned by the same '``freeze``' instruction are 11232guaranteed to always observe the same value, while different '``freeze``' 11233instructions may yield different values. 11234 11235While ``undef`` and ``poison`` pointers can be frozen, the result is a 11236non-dereferenceable pointer. See the 11237:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more information. 11238If an aggregate value or vector is frozen, the operand is frozen element-wise. 11239The padding of an aggregate isn't considered, since it isn't visible 11240without storing it into memory and loading it with a different type. 11241 11242 11243Example: 11244"""""""" 11245 11246.. code-block:: text 11247 11248 %w = i32 undef 11249 %x = freeze i32 %w 11250 %y = add i32 %w, %w ; undef 11251 %z = add i32 %x, %x ; even number because all uses of %x observe 11252 ; the same value 11253 %x2 = freeze i32 %w 11254 %cmp = icmp eq i32 %x, %x2 ; can be true or false 11255 11256 ; example with vectors 11257 %v = <2 x i32> <i32 undef, i32 poison> 11258 %a = extractelement <2 x i32> %v, i32 0 ; undef 11259 %b = extractelement <2 x i32> %v, i32 1 ; poison 11260 %add = add i32 %a, %a ; undef 11261 11262 %v.fr = freeze <2 x i32> %v ; element-wise freeze 11263 %d = extractelement <2 x i32> %v.fr, i32 0 ; not undef 11264 %add.f = add i32 %d, %d ; even number 11265 11266 ; branching on frozen value 11267 %poison = add nsw i1 %k, undef ; poison 11268 %c = freeze i1 %poison 11269 br i1 %c, label %foo, label %bar ; non-deterministic branch to %foo or %bar 11270 11271 11272.. _i_call: 11273 11274'``call``' Instruction 11275^^^^^^^^^^^^^^^^^^^^^^ 11276 11277Syntax: 11278""""""" 11279 11280:: 11281 11282 <result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)] 11283 <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ] 11284 11285Overview: 11286""""""""" 11287 11288The '``call``' instruction represents a simple function call. 11289 11290Arguments: 11291"""""""""" 11292 11293This instruction requires several arguments: 11294 11295#. The optional ``tail`` and ``musttail`` markers indicate that the optimizers 11296 should perform tail call optimization. The ``tail`` marker is a hint that 11297 `can be ignored <CodeGenerator.html#sibcallopt>`_. The ``musttail`` marker 11298 means that the call must be tail call optimized in order for the program to 11299 be correct. The ``musttail`` marker provides these guarantees: 11300 11301 #. The call will not cause unbounded stack growth if it is part of a 11302 recursive cycle in the call graph. 11303 #. Arguments with the :ref:`inalloca <attr_inalloca>` or 11304 :ref:`preallocated <attr_preallocated>` attribute are forwarded in place. 11305 #. If the musttail call appears in a function with the ``"thunk"`` attribute 11306 and the caller and callee both have varargs, than any unprototyped 11307 arguments in register or memory are forwarded to the callee. Similarly, 11308 the return value of the callee is returned to the caller's caller, even 11309 if a void return type is in use. 11310 11311 Both markers imply that the callee does not access allocas from the caller. 11312 The ``tail`` marker additionally implies that the callee does not access 11313 varargs from the caller. Calls marked ``musttail`` must obey the following 11314 additional rules: 11315 11316 - The call must immediately precede a :ref:`ret <i_ret>` instruction, 11317 or a pointer bitcast followed by a ret instruction. 11318 - The ret instruction must return the (possibly bitcasted) value 11319 produced by the call or void. 11320 - The caller and callee prototypes must match. Pointer types of 11321 parameters or return types may differ in pointee type, but not 11322 in address space. 11323 - The calling conventions of the caller and callee must match. 11324 - All ABI-impacting function attributes, such as sret, byval, inreg, 11325 returned, and inalloca, must match. 11326 - The callee must be varargs iff the caller is varargs. Bitcasting a 11327 non-varargs function to the appropriate varargs type is legal so 11328 long as the non-varargs prefixes obey the other rules. 11329 11330 Tail call optimization for calls marked ``tail`` is guaranteed to occur if 11331 the following conditions are met: 11332 11333 - Caller and callee both have the calling convention ``fastcc`` or ``tailcc``. 11334 - The call is in tail position (ret immediately follows call and ret 11335 uses value of call or is void). 11336 - Option ``-tailcallopt`` is enabled, 11337 ``llvm::GuaranteedTailCallOpt`` is ``true``, or the calling convention 11338 is ``tailcc`` 11339 - `Platform-specific constraints are 11340 met. <CodeGenerator.html#tailcallopt>`_ 11341 11342#. The optional ``notail`` marker indicates that the optimizers should not add 11343 ``tail`` or ``musttail`` markers to the call. It is used to prevent tail 11344 call optimization from being performed on the call. 11345 11346#. The optional ``fast-math flags`` marker indicates that the call has one or more 11347 :ref:`fast-math flags <fastmath>`, which are optimization hints to enable 11348 otherwise unsafe floating-point optimizations. Fast-math flags are only valid 11349 for calls that return a floating-point scalar or vector type, or an array 11350 (nested to any depth) of floating-point scalar or vector types. 11351 11352#. The optional "cconv" marker indicates which :ref:`calling 11353 convention <callingconv>` the call should use. If none is 11354 specified, the call defaults to using C calling conventions. The 11355 calling convention of the call must match the calling convention of 11356 the target function, or else the behavior is undefined. 11357#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 11358 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 11359 are valid here. 11360#. The optional addrspace attribute can be used to indicate the address space 11361 of the called function. If it is not specified, the program address space 11362 from the :ref:`datalayout string<langref_datalayout>` will be used. 11363#. '``ty``': the type of the call instruction itself which is also the 11364 type of the return value. Functions that return no value are marked 11365 ``void``. 11366#. '``fnty``': shall be the signature of the function being called. The 11367 argument types must match the types implied by this signature. This 11368 type can be omitted if the function is not varargs. 11369#. '``fnptrval``': An LLVM value containing a pointer to a function to 11370 be called. In most cases, this is a direct function call, but 11371 indirect ``call``'s are just as possible, calling an arbitrary pointer 11372 to function value. 11373#. '``function args``': argument list whose types match the function 11374 signature argument types and parameter attributes. All arguments must 11375 be of :ref:`first class <t_firstclass>` type. If the function signature 11376 indicates the function accepts a variable number of arguments, the 11377 extra arguments can be specified. 11378#. The optional :ref:`function attributes <fnattrs>` list. 11379#. The optional :ref:`operand bundles <opbundles>` list. 11380 11381Semantics: 11382"""""""""" 11383 11384The '``call``' instruction is used to cause control flow to transfer to 11385a specified function, with its incoming arguments bound to the specified 11386values. Upon a '``ret``' instruction in the called function, control 11387flow continues with the instruction after the function call, and the 11388return value of the function is bound to the result argument. 11389 11390Example: 11391"""""""" 11392 11393.. code-block:: llvm 11394 11395 %retval = call i32 @test(i32 %argc) 11396 call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) ; yields i32 11397 %X = tail call i32 @foo() ; yields i32 11398 %Y = tail call fastcc i32 @foo() ; yields i32 11399 call void %foo(i8 97 signext) 11400 11401 %struct.A = type { i32, i8 } 11402 %r = call %struct.A @foo() ; yields { i32, i8 } 11403 %gr = extractvalue %struct.A %r, 0 ; yields i32 11404 %gr1 = extractvalue %struct.A %r, 1 ; yields i8 11405 %Z = call void @foo() noreturn ; indicates that %foo never returns normally 11406 %ZZ = call zeroext i32 @bar() ; Return value is %zero extended 11407 11408llvm treats calls to some functions with names and arguments that match 11409the standard C99 library as being the C99 library functions, and may 11410perform optimizations or generate code for them under that assumption. 11411This is something we'd like to change in the future to provide better 11412support for freestanding environments and non-C-based languages. 11413 11414.. _i_va_arg: 11415 11416'``va_arg``' Instruction 11417^^^^^^^^^^^^^^^^^^^^^^^^ 11418 11419Syntax: 11420""""""" 11421 11422:: 11423 11424 <resultval> = va_arg <va_list*> <arglist>, <argty> 11425 11426Overview: 11427""""""""" 11428 11429The '``va_arg``' instruction is used to access arguments passed through 11430the "variable argument" area of a function call. It is used to implement 11431the ``va_arg`` macro in C. 11432 11433Arguments: 11434"""""""""" 11435 11436This instruction takes a ``va_list*`` value and the type of the 11437argument. It returns a value of the specified argument type and 11438increments the ``va_list`` to point to the next argument. The actual 11439type of ``va_list`` is target specific. 11440 11441Semantics: 11442"""""""""" 11443 11444The '``va_arg``' instruction loads an argument of the specified type 11445from the specified ``va_list`` and causes the ``va_list`` to point to 11446the next argument. For more information, see the variable argument 11447handling :ref:`Intrinsic Functions <int_varargs>`. 11448 11449It is legal for this instruction to be called in a function which does 11450not take a variable number of arguments, for example, the ``vfprintf`` 11451function. 11452 11453``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic 11454function <intrinsics>` because it takes a type as an argument. 11455 11456Example: 11457"""""""" 11458 11459See the :ref:`variable argument processing <int_varargs>` section. 11460 11461Note that the code generator does not yet fully support va\_arg on many 11462targets. Also, it does not currently support va\_arg with aggregate 11463types on any target. 11464 11465.. _i_landingpad: 11466 11467'``landingpad``' Instruction 11468^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11469 11470Syntax: 11471""""""" 11472 11473:: 11474 11475 <resultval> = landingpad <resultty> <clause>+ 11476 <resultval> = landingpad <resultty> cleanup <clause>* 11477 11478 <clause> := catch <type> <value> 11479 <clause> := filter <array constant type> <array constant> 11480 11481Overview: 11482""""""""" 11483 11484The '``landingpad``' instruction is used by `LLVM's exception handling 11485system <ExceptionHandling.html#overview>`_ to specify that a basic block 11486is a landing pad --- one where the exception lands, and corresponds to the 11487code found in the ``catch`` portion of a ``try``/``catch`` sequence. It 11488defines values supplied by the :ref:`personality function <personalityfn>` upon 11489re-entry to the function. The ``resultval`` has the type ``resultty``. 11490 11491Arguments: 11492"""""""""" 11493 11494The optional 11495``cleanup`` flag indicates that the landing pad block is a cleanup. 11496 11497A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and 11498contains the global variable representing the "type" that may be caught 11499or filtered respectively. Unlike the ``catch`` clause, the ``filter`` 11500clause takes an array constant as its argument. Use 11501"``[0 x i8**] undef``" for a filter which cannot throw. The 11502'``landingpad``' instruction must contain *at least* one ``clause`` or 11503the ``cleanup`` flag. 11504 11505Semantics: 11506"""""""""" 11507 11508The '``landingpad``' instruction defines the values which are set by the 11509:ref:`personality function <personalityfn>` upon re-entry to the function, and 11510therefore the "result type" of the ``landingpad`` instruction. As with 11511calling conventions, how the personality function results are 11512represented in LLVM IR is target specific. 11513 11514The clauses are applied in order from top to bottom. If two 11515``landingpad`` instructions are merged together through inlining, the 11516clauses from the calling function are appended to the list of clauses. 11517When the call stack is being unwound due to an exception being thrown, 11518the exception is compared against each ``clause`` in turn. If it doesn't 11519match any of the clauses, and the ``cleanup`` flag is not set, then 11520unwinding continues further up the call stack. 11521 11522The ``landingpad`` instruction has several restrictions: 11523 11524- A landing pad block is a basic block which is the unwind destination 11525 of an '``invoke``' instruction. 11526- A landing pad block must have a '``landingpad``' instruction as its 11527 first non-PHI instruction. 11528- There can be only one '``landingpad``' instruction within the landing 11529 pad block. 11530- A basic block that is not a landing pad block may not include a 11531 '``landingpad``' instruction. 11532 11533Example: 11534"""""""" 11535 11536.. code-block:: llvm 11537 11538 ;; A landing pad which can catch an integer. 11539 %res = landingpad { i8*, i32 } 11540 catch i8** @_ZTIi 11541 ;; A landing pad that is a cleanup. 11542 %res = landingpad { i8*, i32 } 11543 cleanup 11544 ;; A landing pad which can catch an integer and can only throw a double. 11545 %res = landingpad { i8*, i32 } 11546 catch i8** @_ZTIi 11547 filter [1 x i8**] [@_ZTId] 11548 11549.. _i_catchpad: 11550 11551'``catchpad``' Instruction 11552^^^^^^^^^^^^^^^^^^^^^^^^^^ 11553 11554Syntax: 11555""""""" 11556 11557:: 11558 11559 <resultval> = catchpad within <catchswitch> [<args>*] 11560 11561Overview: 11562""""""""" 11563 11564The '``catchpad``' instruction is used by `LLVM's exception handling 11565system <ExceptionHandling.html#overview>`_ to specify that a basic block 11566begins a catch handler --- one where a personality routine attempts to transfer 11567control to catch an exception. 11568 11569Arguments: 11570"""""""""" 11571 11572The ``catchswitch`` operand must always be a token produced by a 11573:ref:`catchswitch <i_catchswitch>` instruction in a predecessor block. This 11574ensures that each ``catchpad`` has exactly one predecessor block, and it always 11575terminates in a ``catchswitch``. 11576 11577The ``args`` correspond to whatever information the personality routine 11578requires to know if this is an appropriate handler for the exception. Control 11579will transfer to the ``catchpad`` if this is the first appropriate handler for 11580the exception. 11581 11582The ``resultval`` has the type :ref:`token <t_token>` and is used to match the 11583``catchpad`` to corresponding :ref:`catchrets <i_catchret>` and other nested EH 11584pads. 11585 11586Semantics: 11587"""""""""" 11588 11589When the call stack is being unwound due to an exception being thrown, the 11590exception is compared against the ``args``. If it doesn't match, control will 11591not reach the ``catchpad`` instruction. The representation of ``args`` is 11592entirely target and personality function-specific. 11593 11594Like the :ref:`landingpad <i_landingpad>` instruction, the ``catchpad`` 11595instruction must be the first non-phi of its parent basic block. 11596 11597The meaning of the tokens produced and consumed by ``catchpad`` and other "pad" 11598instructions is described in the 11599`Windows exception handling documentation\ <ExceptionHandling.html#wineh>`_. 11600 11601When a ``catchpad`` has been "entered" but not yet "exited" (as 11602described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 11603it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 11604that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`. 11605 11606Example: 11607"""""""" 11608 11609.. code-block:: text 11610 11611 dispatch: 11612 %cs = catchswitch within none [label %handler0] unwind to caller 11613 ;; A catch block which can catch an integer. 11614 handler0: 11615 %tok = catchpad within %cs [i8** @_ZTIi] 11616 11617.. _i_cleanuppad: 11618 11619'``cleanuppad``' Instruction 11620^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11621 11622Syntax: 11623""""""" 11624 11625:: 11626 11627 <resultval> = cleanuppad within <parent> [<args>*] 11628 11629Overview: 11630""""""""" 11631 11632The '``cleanuppad``' instruction is used by `LLVM's exception handling 11633system <ExceptionHandling.html#overview>`_ to specify that a basic block 11634is a cleanup block --- one where a personality routine attempts to 11635transfer control to run cleanup actions. 11636The ``args`` correspond to whatever additional 11637information the :ref:`personality function <personalityfn>` requires to 11638execute the cleanup. 11639The ``resultval`` has the type :ref:`token <t_token>` and is used to 11640match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`. 11641The ``parent`` argument is the token of the funclet that contains the 11642``cleanuppad`` instruction. If the ``cleanuppad`` is not inside a funclet, 11643this operand may be the token ``none``. 11644 11645Arguments: 11646"""""""""" 11647 11648The instruction takes a list of arbitrary values which are interpreted 11649by the :ref:`personality function <personalityfn>`. 11650 11651Semantics: 11652"""""""""" 11653 11654When the call stack is being unwound due to an exception being thrown, 11655the :ref:`personality function <personalityfn>` transfers control to the 11656``cleanuppad`` with the aid of the personality-specific arguments. 11657As with calling conventions, how the personality function results are 11658represented in LLVM IR is target specific. 11659 11660The ``cleanuppad`` instruction has several restrictions: 11661 11662- A cleanup block is a basic block which is the unwind destination of 11663 an exceptional instruction. 11664- A cleanup block must have a '``cleanuppad``' instruction as its 11665 first non-PHI instruction. 11666- There can be only one '``cleanuppad``' instruction within the 11667 cleanup block. 11668- A basic block that is not a cleanup block may not include a 11669 '``cleanuppad``' instruction. 11670 11671When a ``cleanuppad`` has been "entered" but not yet "exited" (as 11672described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 11673it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 11674that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`. 11675 11676Example: 11677"""""""" 11678 11679.. code-block:: text 11680 11681 %tok = cleanuppad within %cs [] 11682 11683.. _intrinsics: 11684 11685Intrinsic Functions 11686=================== 11687 11688LLVM supports the notion of an "intrinsic function". These functions 11689have well known names and semantics and are required to follow certain 11690restrictions. Overall, these intrinsics represent an extension mechanism 11691for the LLVM language that does not require changing all of the 11692transformations in LLVM when adding to the language (or the bitcode 11693reader/writer, the parser, etc...). 11694 11695Intrinsic function names must all start with an "``llvm.``" prefix. This 11696prefix is reserved in LLVM for intrinsic names; thus, function names may 11697not begin with this prefix. Intrinsic functions must always be external 11698functions: you cannot define the body of intrinsic functions. Intrinsic 11699functions may only be used in call or invoke instructions: it is illegal 11700to take the address of an intrinsic function. Additionally, because 11701intrinsic functions are part of the LLVM language, it is required if any 11702are added that they be documented here. 11703 11704Some intrinsic functions can be overloaded, i.e., the intrinsic 11705represents a family of functions that perform the same operation but on 11706different data types. Because LLVM can represent over 8 million 11707different integer types, overloading is used commonly to allow an 11708intrinsic function to operate on any integer type. One or more of the 11709argument types or the result type can be overloaded to accept any 11710integer type. Argument types may also be defined as exactly matching a 11711previous argument's type or the result type. This allows an intrinsic 11712function which accepts multiple arguments, but needs all of them to be 11713of the same type, to only be overloaded with respect to a single 11714argument or the result. 11715 11716Overloaded intrinsics will have the names of its overloaded argument 11717types encoded into its function name, each preceded by a period. Only 11718those types which are overloaded result in a name suffix. Arguments 11719whose type is matched against another type do not. For example, the 11720``llvm.ctpop`` function can take an integer of any width and returns an 11721integer of exactly the same integer width. This leads to a family of 11722functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and 11723``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is 11724overloaded, and only one type suffix is required. Because the argument's 11725type is matched against the return type, it does not require its own 11726name suffix. 11727 11728:ref:`Unnamed types <t_opaque>` are encoded as ``s_s``. Overloaded intrinsics 11729that depend on an unnamed type in one of its overloaded argument types get an 11730additional ``.<number>`` suffix. This allows differentiating intrinsics with 11731different unnamed types as arguments. (For example: 11732``llvm.ssa.copy.p0s_s.2(%42*)``) The number is tracked in the LLVM module and 11733it ensures unique names in the module. While linking together two modules, it is 11734still possible to get a name clash. In that case one of the names will be 11735changed by getting a new number. 11736 11737For target developers who are defining intrinsics for back-end code 11738generation, any intrinsic overloads based solely the distinction between 11739integer or floating point types should not be relied upon for correct 11740code generation. In such cases, the recommended approach for target 11741maintainers when defining intrinsics is to create separate integer and 11742FP intrinsics rather than rely on overloading. For example, if different 11743codegen is required for ``llvm.target.foo(<4 x i32>)`` and 11744``llvm.target.foo(<4 x float>)`` then these should be split into 11745different intrinsics. 11746 11747To learn how to add an intrinsic function, please see the `Extending 11748LLVM Guide <ExtendingLLVM.html>`_. 11749 11750.. _int_varargs: 11751 11752Variable Argument Handling Intrinsics 11753------------------------------------- 11754 11755Variable argument support is defined in LLVM with the 11756:ref:`va_arg <i_va_arg>` instruction and these three intrinsic 11757functions. These functions are related to the similarly named macros 11758defined in the ``<stdarg.h>`` header file. 11759 11760All of these functions operate on arguments that use a target-specific 11761value type "``va_list``". The LLVM assembly language reference manual 11762does not define what this type is, so all transformations should be 11763prepared to handle these functions regardless of the type used. 11764 11765This example shows how the :ref:`va_arg <i_va_arg>` instruction and the 11766variable argument handling intrinsic functions are used. 11767 11768.. code-block:: llvm 11769 11770 ; This struct is different for every platform. For most platforms, 11771 ; it is merely an i8*. 11772 %struct.va_list = type { i8* } 11773 11774 ; For Unix x86_64 platforms, va_list is the following struct: 11775 ; %struct.va_list = type { i32, i32, i8*, i8* } 11776 11777 define i32 @test(i32 %X, ...) { 11778 ; Initialize variable argument processing 11779 %ap = alloca %struct.va_list 11780 %ap2 = bitcast %struct.va_list* %ap to i8* 11781 call void @llvm.va_start(i8* %ap2) 11782 11783 ; Read a single integer argument 11784 %tmp = va_arg i8* %ap2, i32 11785 11786 ; Demonstrate usage of llvm.va_copy and llvm.va_end 11787 %aq = alloca i8* 11788 %aq2 = bitcast i8** %aq to i8* 11789 call void @llvm.va_copy(i8* %aq2, i8* %ap2) 11790 call void @llvm.va_end(i8* %aq2) 11791 11792 ; Stop processing of arguments. 11793 call void @llvm.va_end(i8* %ap2) 11794 ret i32 %tmp 11795 } 11796 11797 declare void @llvm.va_start(i8*) 11798 declare void @llvm.va_copy(i8*, i8*) 11799 declare void @llvm.va_end(i8*) 11800 11801.. _int_va_start: 11802 11803'``llvm.va_start``' Intrinsic 11804^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11805 11806Syntax: 11807""""""" 11808 11809:: 11810 11811 declare void @llvm.va_start(i8* <arglist>) 11812 11813Overview: 11814""""""""" 11815 11816The '``llvm.va_start``' intrinsic initializes ``*<arglist>`` for 11817subsequent use by ``va_arg``. 11818 11819Arguments: 11820"""""""""" 11821 11822The argument is a pointer to a ``va_list`` element to initialize. 11823 11824Semantics: 11825"""""""""" 11826 11827The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro 11828available in C. In a target-dependent way, it initializes the 11829``va_list`` element to which the argument points, so that the next call 11830to ``va_arg`` will produce the first variable argument passed to the 11831function. Unlike the C ``va_start`` macro, this intrinsic does not need 11832to know the last argument of the function as the compiler can figure 11833that out. 11834 11835'``llvm.va_end``' Intrinsic 11836^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11837 11838Syntax: 11839""""""" 11840 11841:: 11842 11843 declare void @llvm.va_end(i8* <arglist>) 11844 11845Overview: 11846""""""""" 11847 11848The '``llvm.va_end``' intrinsic destroys ``*<arglist>``, which has been 11849initialized previously with ``llvm.va_start`` or ``llvm.va_copy``. 11850 11851Arguments: 11852"""""""""" 11853 11854The argument is a pointer to a ``va_list`` to destroy. 11855 11856Semantics: 11857"""""""""" 11858 11859The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro 11860available in C. In a target-dependent way, it destroys the ``va_list`` 11861element to which the argument points. Calls to 11862:ref:`llvm.va_start <int_va_start>` and 11863:ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to 11864``llvm.va_end``. 11865 11866.. _int_va_copy: 11867 11868'``llvm.va_copy``' Intrinsic 11869^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11870 11871Syntax: 11872""""""" 11873 11874:: 11875 11876 declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>) 11877 11878Overview: 11879""""""""" 11880 11881The '``llvm.va_copy``' intrinsic copies the current argument position 11882from the source argument list to the destination argument list. 11883 11884Arguments: 11885"""""""""" 11886 11887The first argument is a pointer to a ``va_list`` element to initialize. 11888The second argument is a pointer to a ``va_list`` element to copy from. 11889 11890Semantics: 11891"""""""""" 11892 11893The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro 11894available in C. In a target-dependent way, it copies the source 11895``va_list`` element into the destination ``va_list`` element. This 11896intrinsic is necessary because the `` llvm.va_start`` intrinsic may be 11897arbitrarily complex and require, for example, memory allocation. 11898 11899Accurate Garbage Collection Intrinsics 11900-------------------------------------- 11901 11902LLVM's support for `Accurate Garbage Collection <GarbageCollection.html>`_ 11903(GC) requires the frontend to generate code containing appropriate intrinsic 11904calls and select an appropriate GC strategy which knows how to lower these 11905intrinsics in a manner which is appropriate for the target collector. 11906 11907These intrinsics allow identification of :ref:`GC roots on the 11908stack <int_gcroot>`, as well as garbage collector implementations that 11909require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. 11910Frontends for type-safe garbage collected languages should generate 11911these intrinsics to make use of the LLVM garbage collectors. For more 11912details, see `Garbage Collection with LLVM <GarbageCollection.html>`_. 11913 11914LLVM provides an second experimental set of intrinsics for describing garbage 11915collection safepoints in compiled code. These intrinsics are an alternative 11916to the ``llvm.gcroot`` intrinsics, but are compatible with the ones for 11917:ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. The 11918differences in approach are covered in the `Garbage Collection with LLVM 11919<GarbageCollection.html>`_ documentation. The intrinsics themselves are 11920described in :doc:`Statepoints`. 11921 11922.. _int_gcroot: 11923 11924'``llvm.gcroot``' Intrinsic 11925^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11926 11927Syntax: 11928""""""" 11929 11930:: 11931 11932 declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata) 11933 11934Overview: 11935""""""""" 11936 11937The '``llvm.gcroot``' intrinsic declares the existence of a GC root to 11938the code generator, and allows some metadata to be associated with it. 11939 11940Arguments: 11941"""""""""" 11942 11943The first argument specifies the address of a stack object that contains 11944the root pointer. The second pointer (which must be either a constant or 11945a global value address) contains the meta-data to be associated with the 11946root. 11947 11948Semantics: 11949"""""""""" 11950 11951At runtime, a call to this intrinsic stores a null pointer into the 11952"ptrloc" location. At compile-time, the code generator generates 11953information to allow the runtime to find the pointer at GC safe points. 11954The '``llvm.gcroot``' intrinsic may only be used in a function which 11955:ref:`specifies a GC algorithm <gc>`. 11956 11957.. _int_gcread: 11958 11959'``llvm.gcread``' Intrinsic 11960^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11961 11962Syntax: 11963""""""" 11964 11965:: 11966 11967 declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr) 11968 11969Overview: 11970""""""""" 11971 11972The '``llvm.gcread``' intrinsic identifies reads of references from heap 11973locations, allowing garbage collector implementations that require read 11974barriers. 11975 11976Arguments: 11977"""""""""" 11978 11979The second argument is the address to read from, which should be an 11980address allocated from the garbage collector. The first object is a 11981pointer to the start of the referenced object, if needed by the language 11982runtime (otherwise null). 11983 11984Semantics: 11985"""""""""" 11986 11987The '``llvm.gcread``' intrinsic has the same semantics as a load 11988instruction, but may be replaced with substantially more complex code by 11989the garbage collector runtime, as needed. The '``llvm.gcread``' 11990intrinsic may only be used in a function which :ref:`specifies a GC 11991algorithm <gc>`. 11992 11993.. _int_gcwrite: 11994 11995'``llvm.gcwrite``' Intrinsic 11996^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11997 11998Syntax: 11999""""""" 12000 12001:: 12002 12003 declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2) 12004 12005Overview: 12006""""""""" 12007 12008The '``llvm.gcwrite``' intrinsic identifies writes of references to heap 12009locations, allowing garbage collector implementations that require write 12010barriers (such as generational or reference counting collectors). 12011 12012Arguments: 12013"""""""""" 12014 12015The first argument is the reference to store, the second is the start of 12016the object to store it to, and the third is the address of the field of 12017Obj to store to. If the runtime does not require a pointer to the 12018object, Obj may be null. 12019 12020Semantics: 12021"""""""""" 12022 12023The '``llvm.gcwrite``' intrinsic has the same semantics as a store 12024instruction, but may be replaced with substantially more complex code by 12025the garbage collector runtime, as needed. The '``llvm.gcwrite``' 12026intrinsic may only be used in a function which :ref:`specifies a GC 12027algorithm <gc>`. 12028 12029 12030.. _gc_statepoint: 12031 12032'llvm.experimental.gc.statepoint' Intrinsic 12033^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12034 12035Syntax: 12036""""""" 12037 12038:: 12039 12040 declare token 12041 @llvm.experimental.gc.statepoint(i64 <id>, i32 <num patch bytes>, 12042 func_type <target>, 12043 i64 <#call args>, i64 <flags>, 12044 ... (call parameters), 12045 i64 0, i64 0) 12046 12047Overview: 12048""""""""" 12049 12050The statepoint intrinsic represents a call which is parse-able by the 12051runtime. 12052 12053Operands: 12054""""""""" 12055 12056The 'id' operand is a constant integer that is reported as the ID 12057field in the generated stackmap. LLVM does not interpret this 12058parameter in any way and its meaning is up to the statepoint user to 12059decide. Note that LLVM is free to duplicate code containing 12060statepoint calls, and this may transform IR that had a unique 'id' per 12061lexical call to statepoint to IR that does not. 12062 12063If 'num patch bytes' is non-zero then the call instruction 12064corresponding to the statepoint is not emitted and LLVM emits 'num 12065patch bytes' bytes of nops in its place. LLVM will emit code to 12066prepare the function arguments and retrieve the function return value 12067in accordance to the calling convention; the former before the nop 12068sequence and the latter after the nop sequence. It is expected that 12069the user will patch over the 'num patch bytes' bytes of nops with a 12070calling sequence specific to their runtime before executing the 12071generated machine code. There are no guarantees with respect to the 12072alignment of the nop sequence. Unlike :doc:`StackMaps` statepoints do 12073not have a concept of shadow bytes. Note that semantically the 12074statepoint still represents a call or invoke to 'target', and the nop 12075sequence after patching is expected to represent an operation 12076equivalent to a call or invoke to 'target'. 12077 12078The 'target' operand is the function actually being called. The 12079target can be specified as either a symbolic LLVM function, or as an 12080arbitrary Value of appropriate function type. Note that the function 12081type must match the signature of the callee and the types of the 'call 12082parameters' arguments. 12083 12084The '#call args' operand is the number of arguments to the actual 12085call. It must exactly match the number of arguments passed in the 12086'call parameters' variable length section. 12087 12088The 'flags' operand is used to specify extra information about the 12089statepoint. This is currently only used to mark certain statepoints 12090as GC transitions. This operand is a 64-bit integer with the following 12091layout, where bit 0 is the least significant bit: 12092 12093 +-------+---------------------------------------------------+ 12094 | Bit # | Usage | 12095 +=======+===================================================+ 12096 | 0 | Set if the statepoint is a GC transition, cleared | 12097 | | otherwise. | 12098 +-------+---------------------------------------------------+ 12099 | 1-63 | Reserved for future use; must be cleared. | 12100 +-------+---------------------------------------------------+ 12101 12102The 'call parameters' arguments are simply the arguments which need to 12103be passed to the call target. They will be lowered according to the 12104specified calling convention and otherwise handled like a normal call 12105instruction. The number of arguments must exactly match what is 12106specified in '# call args'. The types must match the signature of 12107'target'. 12108 12109The 'call parameter' attributes must be followed by two 'i64 0' constants. 12110These were originally the length prefixes for 'gc transition parameter' and 12111'deopt parameter' arguments, but the role of these parameter sets have been 12112entirely replaced with the corresponding operand bundles. In a future 12113revision, these now redundant arguments will be removed. 12114 12115Semantics: 12116"""""""""" 12117 12118A statepoint is assumed to read and write all memory. As a result, 12119memory operations can not be reordered past a statepoint. It is 12120illegal to mark a statepoint as being either 'readonly' or 'readnone'. 12121 12122Note that legal IR can not perform any memory operation on a 'gc 12123pointer' argument of the statepoint in a location statically reachable 12124from the statepoint. Instead, the explicitly relocated value (from a 12125``gc.relocate``) must be used. 12126 12127'llvm.experimental.gc.result' Intrinsic 12128^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12129 12130Syntax: 12131""""""" 12132 12133:: 12134 12135 declare type* 12136 @llvm.experimental.gc.result(token %statepoint_token) 12137 12138Overview: 12139""""""""" 12140 12141``gc.result`` extracts the result of the original call instruction 12142which was replaced by the ``gc.statepoint``. The ``gc.result`` 12143intrinsic is actually a family of three intrinsics due to an 12144implementation limitation. Other than the type of the return value, 12145the semantics are the same. 12146 12147Operands: 12148""""""""" 12149 12150The first and only argument is the ``gc.statepoint`` which starts 12151the safepoint sequence of which this ``gc.result`` is a part. 12152Despite the typing of this as a generic token, *only* the value defined 12153by a ``gc.statepoint`` is legal here. 12154 12155Semantics: 12156"""""""""" 12157 12158The ``gc.result`` represents the return value of the call target of 12159the ``statepoint``. The type of the ``gc.result`` must exactly match 12160the type of the target. If the call target returns void, there will 12161be no ``gc.result``. 12162 12163A ``gc.result`` is modeled as a 'readnone' pure function. It has no 12164side effects since it is just a projection of the return value of the 12165previous call represented by the ``gc.statepoint``. 12166 12167'llvm.experimental.gc.relocate' Intrinsic 12168^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12169 12170Syntax: 12171""""""" 12172 12173:: 12174 12175 declare <pointer type> 12176 @llvm.experimental.gc.relocate(token %statepoint_token, 12177 i32 %base_offset, 12178 i32 %pointer_offset) 12179 12180Overview: 12181""""""""" 12182 12183A ``gc.relocate`` returns the potentially relocated value of a pointer 12184at the safepoint. 12185 12186Operands: 12187""""""""" 12188 12189The first argument is the ``gc.statepoint`` which starts the 12190safepoint sequence of which this ``gc.relocation`` is a part. 12191Despite the typing of this as a generic token, *only* the value defined 12192by a ``gc.statepoint`` is legal here. 12193 12194The second and third arguments are both indices into operands of the 12195corresponding statepoint's :ref:`gc-live <ob_gc_live>` operand bundle. 12196 12197The second argument is an index which specifies the allocation for the pointer 12198being relocated. The associated value must be within the object with which the 12199pointer being relocated is associated. The optimizer is free to change *which* 12200interior derived pointer is reported, provided that it does not replace an 12201actual base pointer with another interior derived pointer. Collectors are 12202allowed to rely on the base pointer operand remaining an actual base pointer if 12203so constructed. 12204 12205The third argument is an index which specify the (potentially) derived pointer 12206being relocated. It is legal for this index to be the same as the second 12207argument if-and-only-if a base pointer is being relocated. 12208 12209Semantics: 12210"""""""""" 12211 12212The return value of ``gc.relocate`` is the potentially relocated value 12213of the pointer specified by its arguments. It is unspecified how the 12214value of the returned pointer relates to the argument to the 12215``gc.statepoint`` other than that a) it points to the same source 12216language object with the same offset, and b) the 'based-on' 12217relationship of the newly relocated pointers is a projection of the 12218unrelocated pointers. In particular, the integer value of the pointer 12219returned is unspecified. 12220 12221A ``gc.relocate`` is modeled as a ``readnone`` pure function. It has no 12222side effects since it is just a way to extract information about work 12223done during the actual call modeled by the ``gc.statepoint``. 12224 12225Code Generator Intrinsics 12226------------------------- 12227 12228These intrinsics are provided by LLVM to expose special features that 12229may only be implemented with code generator support. 12230 12231'``llvm.returnaddress``' Intrinsic 12232^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12233 12234Syntax: 12235""""""" 12236 12237:: 12238 12239 declare i8* @llvm.returnaddress(i32 <level>) 12240 12241Overview: 12242""""""""" 12243 12244The '``llvm.returnaddress``' intrinsic attempts to compute a 12245target-specific value indicating the return address of the current 12246function or one of its callers. 12247 12248Arguments: 12249"""""""""" 12250 12251The argument to this intrinsic indicates which function to return the 12252address for. Zero indicates the calling function, one indicates its 12253caller, etc. The argument is **required** to be a constant integer 12254value. 12255 12256Semantics: 12257"""""""""" 12258 12259The '``llvm.returnaddress``' intrinsic either returns a pointer 12260indicating the return address of the specified call frame, or zero if it 12261cannot be identified. The value returned by this intrinsic is likely to 12262be incorrect or 0 for arguments other than zero, so it should only be 12263used for debugging purposes. 12264 12265Note that calling this intrinsic does not prevent function inlining or 12266other aggressive transformations, so the value returned may not be that 12267of the obvious source-language caller. 12268 12269'``llvm.addressofreturnaddress``' Intrinsic 12270^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12271 12272Syntax: 12273""""""" 12274 12275:: 12276 12277 declare i8* @llvm.addressofreturnaddress() 12278 12279Overview: 12280""""""""" 12281 12282The '``llvm.addressofreturnaddress``' intrinsic returns a target-specific 12283pointer to the place in the stack frame where the return address of the 12284current function is stored. 12285 12286Semantics: 12287"""""""""" 12288 12289Note that calling this intrinsic does not prevent function inlining or 12290other aggressive transformations, so the value returned may not be that 12291of the obvious source-language caller. 12292 12293This intrinsic is only implemented for x86 and aarch64. 12294 12295'``llvm.sponentry``' Intrinsic 12296^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12297 12298Syntax: 12299""""""" 12300 12301:: 12302 12303 declare i8* @llvm.sponentry() 12304 12305Overview: 12306""""""""" 12307 12308The '``llvm.sponentry``' intrinsic returns the stack pointer value at 12309the entry of the current function calling this intrinsic. 12310 12311Semantics: 12312"""""""""" 12313 12314Note this intrinsic is only verified on AArch64. 12315 12316'``llvm.frameaddress``' Intrinsic 12317^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12318 12319Syntax: 12320""""""" 12321 12322:: 12323 12324 declare i8* @llvm.frameaddress(i32 <level>) 12325 12326Overview: 12327""""""""" 12328 12329The '``llvm.frameaddress``' intrinsic attempts to return the 12330target-specific frame pointer value for the specified stack frame. 12331 12332Arguments: 12333"""""""""" 12334 12335The argument to this intrinsic indicates which function to return the 12336frame pointer for. Zero indicates the calling function, one indicates 12337its caller, etc. The argument is **required** to be a constant integer 12338value. 12339 12340Semantics: 12341"""""""""" 12342 12343The '``llvm.frameaddress``' intrinsic either returns a pointer 12344indicating the frame address of the specified call frame, or zero if it 12345cannot be identified. The value returned by this intrinsic is likely to 12346be incorrect or 0 for arguments other than zero, so it should only be 12347used for debugging purposes. 12348 12349Note that calling this intrinsic does not prevent function inlining or 12350other aggressive transformations, so the value returned may not be that 12351of the obvious source-language caller. 12352 12353'``llvm.localescape``' and '``llvm.localrecover``' Intrinsics 12354^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12355 12356Syntax: 12357""""""" 12358 12359:: 12360 12361 declare void @llvm.localescape(...) 12362 declare i8* @llvm.localrecover(i8* %func, i8* %fp, i32 %idx) 12363 12364Overview: 12365""""""""" 12366 12367The '``llvm.localescape``' intrinsic escapes offsets of a collection of static 12368allocas, and the '``llvm.localrecover``' intrinsic applies those offsets to a 12369live frame pointer to recover the address of the allocation. The offset is 12370computed during frame layout of the caller of ``llvm.localescape``. 12371 12372Arguments: 12373"""""""""" 12374 12375All arguments to '``llvm.localescape``' must be pointers to static allocas or 12376casts of static allocas. Each function can only call '``llvm.localescape``' 12377once, and it can only do so from the entry block. 12378 12379The ``func`` argument to '``llvm.localrecover``' must be a constant 12380bitcasted pointer to a function defined in the current module. The code 12381generator cannot determine the frame allocation offset of functions defined in 12382other modules. 12383 12384The ``fp`` argument to '``llvm.localrecover``' must be a frame pointer of a 12385call frame that is currently live. The return value of '``llvm.localaddress``' 12386is one way to produce such a value, but various runtimes also expose a suitable 12387pointer in platform-specific ways. 12388 12389The ``idx`` argument to '``llvm.localrecover``' indicates which alloca passed to 12390'``llvm.localescape``' to recover. It is zero-indexed. 12391 12392Semantics: 12393"""""""""" 12394 12395These intrinsics allow a group of functions to share access to a set of local 12396stack allocations of a one parent function. The parent function may call the 12397'``llvm.localescape``' intrinsic once from the function entry block, and the 12398child functions can use '``llvm.localrecover``' to access the escaped allocas. 12399The '``llvm.localescape``' intrinsic blocks inlining, as inlining changes where 12400the escaped allocas are allocated, which would break attempts to use 12401'``llvm.localrecover``'. 12402 12403.. _int_read_register: 12404.. _int_read_volatile_register: 12405.. _int_write_register: 12406 12407'``llvm.read_register``', '``llvm.read_volatile_register``', and 12408'``llvm.write_register``' Intrinsics 12409^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12410 12411Syntax: 12412""""""" 12413 12414:: 12415 12416 declare i32 @llvm.read_register.i32(metadata) 12417 declare i64 @llvm.read_register.i64(metadata) 12418 declare i32 @llvm.read_volatile_register.i32(metadata) 12419 declare i64 @llvm.read_volatile_register.i64(metadata) 12420 declare void @llvm.write_register.i32(metadata, i32 @value) 12421 declare void @llvm.write_register.i64(metadata, i64 @value) 12422 !0 = !{!"sp\00"} 12423 12424Overview: 12425""""""""" 12426 12427The '``llvm.read_register``', '``llvm.read_volatile_register``', and 12428'``llvm.write_register``' intrinsics provide access to the named register. 12429The register must be valid on the architecture being compiled to. The type 12430needs to be compatible with the register being read. 12431 12432Semantics: 12433"""""""""" 12434 12435The '``llvm.read_register``' and '``llvm.read_volatile_register``' intrinsics 12436return the current value of the register, where possible. The 12437'``llvm.write_register``' intrinsic sets the current value of the register, 12438where possible. 12439 12440A call to '``llvm.read_volatile_register``' is assumed to have side-effects 12441and possibly return a different value each time (e.g. for a timer register). 12442 12443This is useful to implement named register global variables that need 12444to always be mapped to a specific register, as is common practice on 12445bare-metal programs including OS kernels. 12446 12447The compiler doesn't check for register availability or use of the used 12448register in surrounding code, including inline assembly. Because of that, 12449allocatable registers are not supported. 12450 12451Warning: So far it only works with the stack pointer on selected 12452architectures (ARM, AArch64, PowerPC and x86_64). Significant amount of 12453work is needed to support other registers and even more so, allocatable 12454registers. 12455 12456.. _int_stacksave: 12457 12458'``llvm.stacksave``' Intrinsic 12459^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12460 12461Syntax: 12462""""""" 12463 12464:: 12465 12466 declare i8* @llvm.stacksave() 12467 12468Overview: 12469""""""""" 12470 12471The '``llvm.stacksave``' intrinsic is used to remember the current state 12472of the function stack, for use with 12473:ref:`llvm.stackrestore <int_stackrestore>`. This is useful for 12474implementing language features like scoped automatic variable sized 12475arrays in C99. 12476 12477Semantics: 12478"""""""""" 12479 12480This intrinsic returns an opaque pointer value that can be passed to 12481:ref:`llvm.stackrestore <int_stackrestore>`. When an 12482``llvm.stackrestore`` intrinsic is executed with a value saved from 12483``llvm.stacksave``, it effectively restores the state of the stack to 12484the state it was in when the ``llvm.stacksave`` intrinsic executed. In 12485practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that 12486were allocated after the ``llvm.stacksave`` was executed. 12487 12488.. _int_stackrestore: 12489 12490'``llvm.stackrestore``' Intrinsic 12491^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12492 12493Syntax: 12494""""""" 12495 12496:: 12497 12498 declare void @llvm.stackrestore(i8* %ptr) 12499 12500Overview: 12501""""""""" 12502 12503The '``llvm.stackrestore``' intrinsic is used to restore the state of 12504the function stack to the state it was in when the corresponding 12505:ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is 12506useful for implementing language features like scoped automatic variable 12507sized arrays in C99. 12508 12509Semantics: 12510"""""""""" 12511 12512See the description for :ref:`llvm.stacksave <int_stacksave>`. 12513 12514.. _int_get_dynamic_area_offset: 12515 12516'``llvm.get.dynamic.area.offset``' Intrinsic 12517^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12518 12519Syntax: 12520""""""" 12521 12522:: 12523 12524 declare i32 @llvm.get.dynamic.area.offset.i32() 12525 declare i64 @llvm.get.dynamic.area.offset.i64() 12526 12527Overview: 12528""""""""" 12529 12530 The '``llvm.get.dynamic.area.offset.*``' intrinsic family is used to 12531 get the offset from native stack pointer to the address of the most 12532 recent dynamic alloca on the caller's stack. These intrinsics are 12533 intended for use in combination with 12534 :ref:`llvm.stacksave <int_stacksave>` to get a 12535 pointer to the most recent dynamic alloca. This is useful, for example, 12536 for AddressSanitizer's stack unpoisoning routines. 12537 12538Semantics: 12539"""""""""" 12540 12541 These intrinsics return a non-negative integer value that can be used to 12542 get the address of the most recent dynamic alloca, allocated by :ref:`alloca <i_alloca>` 12543 on the caller's stack. In particular, for targets where stack grows downwards, 12544 adding this offset to the native stack pointer would get the address of the most 12545 recent dynamic alloca. For targets where stack grows upwards, the situation is a bit more 12546 complicated, because subtracting this value from stack pointer would get the address 12547 one past the end of the most recent dynamic alloca. 12548 12549 Although for most targets `llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>` 12550 returns just a zero, for others, such as PowerPC and PowerPC64, it returns a 12551 compile-time-known constant value. 12552 12553 The return value type of :ref:`llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>` 12554 must match the target's default address space's (address space 0) pointer type. 12555 12556'``llvm.prefetch``' Intrinsic 12557^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12558 12559Syntax: 12560""""""" 12561 12562:: 12563 12564 declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>) 12565 12566Overview: 12567""""""""" 12568 12569The '``llvm.prefetch``' intrinsic is a hint to the code generator to 12570insert a prefetch instruction if supported; otherwise, it is a noop. 12571Prefetches have no effect on the behavior of the program but can change 12572its performance characteristics. 12573 12574Arguments: 12575"""""""""" 12576 12577``address`` is the address to be prefetched, ``rw`` is the specifier 12578determining if the fetch should be for a read (0) or write (1), and 12579``locality`` is a temporal locality specifier ranging from (0) - no 12580locality, to (3) - extremely local keep in cache. The ``cache type`` 12581specifies whether the prefetch is performed on the data (1) or 12582instruction (0) cache. The ``rw``, ``locality`` and ``cache type`` 12583arguments must be constant integers. 12584 12585Semantics: 12586"""""""""" 12587 12588This intrinsic does not modify the behavior of the program. In 12589particular, prefetches cannot trap and do not produce a value. On 12590targets that support this intrinsic, the prefetch can provide hints to 12591the processor cache for better performance. 12592 12593'``llvm.pcmarker``' Intrinsic 12594^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12595 12596Syntax: 12597""""""" 12598 12599:: 12600 12601 declare void @llvm.pcmarker(i32 <id>) 12602 12603Overview: 12604""""""""" 12605 12606The '``llvm.pcmarker``' intrinsic is a method to export a Program 12607Counter (PC) in a region of code to simulators and other tools. The 12608method is target specific, but it is expected that the marker will use 12609exported symbols to transmit the PC of the marker. The marker makes no 12610guarantees that it will remain with any specific instruction after 12611optimizations. It is possible that the presence of a marker will inhibit 12612optimizations. The intended use is to be inserted after optimizations to 12613allow correlations of simulation runs. 12614 12615Arguments: 12616"""""""""" 12617 12618``id`` is a numerical id identifying the marker. 12619 12620Semantics: 12621"""""""""" 12622 12623This intrinsic does not modify the behavior of the program. Backends 12624that do not support this intrinsic may ignore it. 12625 12626'``llvm.readcyclecounter``' Intrinsic 12627^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12628 12629Syntax: 12630""""""" 12631 12632:: 12633 12634 declare i64 @llvm.readcyclecounter() 12635 12636Overview: 12637""""""""" 12638 12639The '``llvm.readcyclecounter``' intrinsic provides access to the cycle 12640counter register (or similar low latency, high accuracy clocks) on those 12641targets that support it. On X86, it should map to RDTSC. On Alpha, it 12642should map to RPCC. As the backing counters overflow quickly (on the 12643order of 9 seconds on alpha), this should only be used for small 12644timings. 12645 12646Semantics: 12647"""""""""" 12648 12649When directly supported, reading the cycle counter should not modify any 12650memory. Implementations are allowed to either return an application 12651specific value or a system wide value. On backends without support, this 12652is lowered to a constant 0. 12653 12654Note that runtime support may be conditional on the privilege-level code is 12655running at and the host platform. 12656 12657'``llvm.clear_cache``' Intrinsic 12658^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12659 12660Syntax: 12661""""""" 12662 12663:: 12664 12665 declare void @llvm.clear_cache(i8*, i8*) 12666 12667Overview: 12668""""""""" 12669 12670The '``llvm.clear_cache``' intrinsic ensures visibility of modifications 12671in the specified range to the execution unit of the processor. On 12672targets with non-unified instruction and data cache, the implementation 12673flushes the instruction cache. 12674 12675Semantics: 12676"""""""""" 12677 12678On platforms with coherent instruction and data caches (e.g. x86), this 12679intrinsic is a nop. On platforms with non-coherent instruction and data 12680cache (e.g. ARM, MIPS), the intrinsic is lowered either to appropriate 12681instructions or a system call, if cache flushing requires special 12682privileges. 12683 12684The default behavior is to emit a call to ``__clear_cache`` from the run 12685time library. 12686 12687This intrinsic does *not* empty the instruction pipeline. Modifications 12688of the current function are outside the scope of the intrinsic. 12689 12690'``llvm.instrprof.increment``' Intrinsic 12691^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12692 12693Syntax: 12694""""""" 12695 12696:: 12697 12698 declare void @llvm.instrprof.increment(i8* <name>, i64 <hash>, 12699 i32 <num-counters>, i32 <index>) 12700 12701Overview: 12702""""""""" 12703 12704The '``llvm.instrprof.increment``' intrinsic can be emitted by a 12705frontend for use with instrumentation based profiling. These will be 12706lowered by the ``-instrprof`` pass to generate execution counts of a 12707program at runtime. 12708 12709Arguments: 12710"""""""""" 12711 12712The first argument is a pointer to a global variable containing the 12713name of the entity being instrumented. This should generally be the 12714(mangled) function name for a set of counters. 12715 12716The second argument is a hash value that can be used by the consumer 12717of the profile data to detect changes to the instrumented source, and 12718the third is the number of counters associated with ``name``. It is an 12719error if ``hash`` or ``num-counters`` differ between two instances of 12720``instrprof.increment`` that refer to the same name. 12721 12722The last argument refers to which of the counters for ``name`` should 12723be incremented. It should be a value between 0 and ``num-counters``. 12724 12725Semantics: 12726"""""""""" 12727 12728This intrinsic represents an increment of a profiling counter. It will 12729cause the ``-instrprof`` pass to generate the appropriate data 12730structures and the code to increment the appropriate value, in a 12731format that can be written out by a compiler runtime and consumed via 12732the ``llvm-profdata`` tool. 12733 12734'``llvm.instrprof.increment.step``' Intrinsic 12735^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12736 12737Syntax: 12738""""""" 12739 12740:: 12741 12742 declare void @llvm.instrprof.increment.step(i8* <name>, i64 <hash>, 12743 i32 <num-counters>, 12744 i32 <index>, i64 <step>) 12745 12746Overview: 12747""""""""" 12748 12749The '``llvm.instrprof.increment.step``' intrinsic is an extension to 12750the '``llvm.instrprof.increment``' intrinsic with an additional fifth 12751argument to specify the step of the increment. 12752 12753Arguments: 12754"""""""""" 12755The first four arguments are the same as '``llvm.instrprof.increment``' 12756intrinsic. 12757 12758The last argument specifies the value of the increment of the counter variable. 12759 12760Semantics: 12761"""""""""" 12762See description of '``llvm.instrprof.increment``' intrinsic. 12763 12764 12765'``llvm.instrprof.value.profile``' Intrinsic 12766^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12767 12768Syntax: 12769""""""" 12770 12771:: 12772 12773 declare void @llvm.instrprof.value.profile(i8* <name>, i64 <hash>, 12774 i64 <value>, i32 <value_kind>, 12775 i32 <index>) 12776 12777Overview: 12778""""""""" 12779 12780The '``llvm.instrprof.value.profile``' intrinsic can be emitted by a 12781frontend for use with instrumentation based profiling. This will be 12782lowered by the ``-instrprof`` pass to find out the target values, 12783instrumented expressions take in a program at runtime. 12784 12785Arguments: 12786"""""""""" 12787 12788The first argument is a pointer to a global variable containing the 12789name of the entity being instrumented. ``name`` should generally be the 12790(mangled) function name for a set of counters. 12791 12792The second argument is a hash value that can be used by the consumer 12793of the profile data to detect changes to the instrumented source. It 12794is an error if ``hash`` differs between two instances of 12795``llvm.instrprof.*`` that refer to the same name. 12796 12797The third argument is the value of the expression being profiled. The profiled 12798expression's value should be representable as an unsigned 64-bit value. The 12799fourth argument represents the kind of value profiling that is being done. The 12800supported value profiling kinds are enumerated through the 12801``InstrProfValueKind`` type declared in the 12802``<include/llvm/ProfileData/InstrProf.h>`` header file. The last argument is the 12803index of the instrumented expression within ``name``. It should be >= 0. 12804 12805Semantics: 12806"""""""""" 12807 12808This intrinsic represents the point where a call to a runtime routine 12809should be inserted for value profiling of target expressions. ``-instrprof`` 12810pass will generate the appropriate data structures and replace the 12811``llvm.instrprof.value.profile`` intrinsic with the call to the profile 12812runtime library with proper arguments. 12813 12814'``llvm.thread.pointer``' Intrinsic 12815^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12816 12817Syntax: 12818""""""" 12819 12820:: 12821 12822 declare i8* @llvm.thread.pointer() 12823 12824Overview: 12825""""""""" 12826 12827The '``llvm.thread.pointer``' intrinsic returns the value of the thread 12828pointer. 12829 12830Semantics: 12831"""""""""" 12832 12833The '``llvm.thread.pointer``' intrinsic returns a pointer to the TLS area 12834for the current thread. The exact semantics of this value are target 12835specific: it may point to the start of TLS area, to the end, or somewhere 12836in the middle. Depending on the target, this intrinsic may read a register, 12837call a helper function, read from an alternate memory space, or perform 12838other operations necessary to locate the TLS area. Not all targets support 12839this intrinsic. 12840 12841'``llvm.call.preallocated.setup``' Intrinsic 12842^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12843 12844Syntax: 12845""""""" 12846 12847:: 12848 12849 declare token @llvm.call.preallocated.setup(i32 %num_args) 12850 12851Overview: 12852""""""""" 12853 12854The '``llvm.call.preallocated.setup``' intrinsic returns a token which can 12855be used with a call's ``"preallocated"`` operand bundle to indicate that 12856certain arguments are allocated and initialized before the call. 12857 12858Semantics: 12859"""""""""" 12860 12861The '``llvm.call.preallocated.setup``' intrinsic returns a token which is 12862associated with at most one call. The token can be passed to 12863'``@llvm.call.preallocated.arg``' to get a pointer to get that 12864corresponding argument. The token must be the parameter to a 12865``"preallocated"`` operand bundle for the corresponding call. 12866 12867Nested calls to '``llvm.call.preallocated.setup``' are allowed, but must 12868be properly nested. e.g. 12869 12870:: code-block:: llvm 12871 12872 %t1 = call token @llvm.call.preallocated.setup(i32 0) 12873 %t2 = call token @llvm.call.preallocated.setup(i32 0) 12874 call void foo() ["preallocated"(token %t2)] 12875 call void foo() ["preallocated"(token %t1)] 12876 12877is allowed, but not 12878 12879:: code-block:: llvm 12880 12881 %t1 = call token @llvm.call.preallocated.setup(i32 0) 12882 %t2 = call token @llvm.call.preallocated.setup(i32 0) 12883 call void foo() ["preallocated"(token %t1)] 12884 call void foo() ["preallocated"(token %t2)] 12885 12886.. _int_call_preallocated_arg: 12887 12888'``llvm.call.preallocated.arg``' Intrinsic 12889^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12890 12891Syntax: 12892""""""" 12893 12894:: 12895 12896 declare i8* @llvm.call.preallocated.arg(token %setup_token, i32 %arg_index) 12897 12898Overview: 12899""""""""" 12900 12901The '``llvm.call.preallocated.arg``' intrinsic returns a pointer to the 12902corresponding preallocated argument for the preallocated call. 12903 12904Semantics: 12905"""""""""" 12906 12907The '``llvm.call.preallocated.arg``' intrinsic returns a pointer to the 12908``%arg_index``th argument with the ``preallocated`` attribute for 12909the call associated with the ``%setup_token``, which must be from 12910'``llvm.call.preallocated.setup``'. 12911 12912A call to '``llvm.call.preallocated.arg``' must have a call site 12913``preallocated`` attribute. The type of the ``preallocated`` attribute must 12914match the type used by the ``preallocated`` attribute of the corresponding 12915argument at the preallocated call. The type is used in the case that an 12916``llvm.call.preallocated.setup`` does not have a corresponding call (e.g. due 12917to DCE), where otherwise we cannot know how large the arguments are. 12918 12919It is undefined behavior if this is called with a token from an 12920'``llvm.call.preallocated.setup``' if another 12921'``llvm.call.preallocated.setup``' has already been called or if the 12922preallocated call corresponding to the '``llvm.call.preallocated.setup``' 12923has already been called. 12924 12925.. _int_call_preallocated_teardown: 12926 12927'``llvm.call.preallocated.teardown``' Intrinsic 12928^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12929 12930Syntax: 12931""""""" 12932 12933:: 12934 12935 declare i8* @llvm.call.preallocated.teardown(token %setup_token) 12936 12937Overview: 12938""""""""" 12939 12940The '``llvm.call.preallocated.teardown``' intrinsic cleans up the stack 12941created by a '``llvm.call.preallocated.setup``'. 12942 12943Semantics: 12944"""""""""" 12945 12946The token argument must be a '``llvm.call.preallocated.setup``'. 12947 12948The '``llvm.call.preallocated.teardown``' intrinsic cleans up the stack 12949allocated by the corresponding '``llvm.call.preallocated.setup``'. Exactly 12950one of this or the preallocated call must be called to prevent stack leaks. 12951It is undefined behavior to call both a '``llvm.call.preallocated.teardown``' 12952and the preallocated call for a given '``llvm.call.preallocated.setup``'. 12953 12954For example, if the stack is allocated for a preallocated call by a 12955'``llvm.call.preallocated.setup``', then an initializer function called on an 12956allocated argument throws an exception, there should be a 12957'``llvm.call.preallocated.teardown``' in the exception handler to prevent 12958stack leaks. 12959 12960Following the nesting rules in '``llvm.call.preallocated.setup``', nested 12961calls to '``llvm.call.preallocated.setup``' and 12962'``llvm.call.preallocated.teardown``' are allowed but must be properly 12963nested. 12964 12965Example: 12966"""""""" 12967 12968.. code-block:: llvm 12969 12970 %cs = call token @llvm.call.preallocated.setup(i32 1) 12971 %x = call i8* @llvm.call.preallocated.arg(token %cs, i32 0) preallocated(i32) 12972 %y = bitcast i8* %x to i32* 12973 invoke void @constructor(i32* %y) to label %conta unwind label %contb 12974 conta: 12975 call void @foo1(i32* preallocated(i32) %y) ["preallocated"(token %cs)] 12976 ret void 12977 contb: 12978 %s = catchswitch within none [label %catch] unwind to caller 12979 catch: 12980 %p = catchpad within %s [] 12981 call void @llvm.call.preallocated.teardown(token %cs) 12982 ret void 12983 12984Standard C/C++ Library Intrinsics 12985--------------------------------- 12986 12987LLVM provides intrinsics for a few important standard C/C++ library 12988functions. These intrinsics allow source-language front-ends to pass 12989information about the alignment of the pointer arguments to the code 12990generator, providing opportunity for more efficient code generation. 12991 12992 12993'``llvm.abs.*``' Intrinsic 12994^^^^^^^^^^^^^^^^^^^^^^^^^^ 12995 12996Syntax: 12997""""""" 12998 12999This is an overloaded intrinsic. You can use ``llvm.abs`` on any 13000integer bit width or any vector of integer elements. 13001 13002:: 13003 13004 declare i32 @llvm.abs.i32(i32 <src>, i1 <is_int_min_poison>) 13005 declare <4 x i32> @llvm.abs.v4i32(<4 x i32> <src>, i1 <is_int_min_poison>) 13006 13007Overview: 13008""""""""" 13009 13010The '``llvm.abs``' family of intrinsic functions returns the absolute value 13011of an argument. 13012 13013Arguments: 13014"""""""""" 13015 13016The first argument is the value for which the absolute value is to be returned. 13017This argument may be of any integer type or a vector with integer element type. 13018The return type must match the first argument type. 13019 13020The second argument must be a constant and is a flag to indicate whether the 13021result value of the '``llvm.abs``' intrinsic is a 13022:ref:`poison value <poisonvalues>` if the argument is statically or dynamically 13023an ``INT_MIN`` value. 13024 13025Semantics: 13026"""""""""" 13027 13028The '``llvm.abs``' intrinsic returns the magnitude (always positive) of the 13029argument or each element of a vector argument.". If the argument is ``INT_MIN``, 13030then the result is also ``INT_MIN`` if ``is_int_min_poison == 0`` and 13031``poison`` otherwise. 13032 13033 13034'``llvm.smax.*``' Intrinsic 13035^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13036 13037Syntax: 13038""""""" 13039 13040This is an overloaded intrinsic. You can use ``@llvm.smax`` on any 13041integer bit width or any vector of integer elements. 13042 13043:: 13044 13045 declare i32 @llvm.smax.i32(i32 %a, i32 %b) 13046 declare <4 x i32> @llvm.smax.v4i32(<4 x i32> %a, <4 x i32> %b) 13047 13048Overview: 13049""""""""" 13050 13051Return the larger of ``%a`` and ``%b`` comparing the values as signed integers. 13052Vector intrinsics operate on a per-element basis. The larger element of ``%a`` 13053and ``%b`` at a given index is returned for that index. 13054 13055Arguments: 13056"""""""""" 13057 13058The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13059integer element type. The argument types must match each other, and the return 13060type must match the argument type. 13061 13062 13063'``llvm.smin.*``' Intrinsic 13064^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13065 13066Syntax: 13067""""""" 13068 13069This is an overloaded intrinsic. You can use ``@llvm.smin`` on any 13070integer bit width or any vector of integer elements. 13071 13072:: 13073 13074 declare i32 @llvm.smin.i32(i32 %a, i32 %b) 13075 declare <4 x i32> @llvm.smin.v4i32(<4 x i32> %a, <4 x i32> %b) 13076 13077Overview: 13078""""""""" 13079 13080Return the smaller of ``%a`` and ``%b`` comparing the values as signed integers. 13081Vector intrinsics operate on a per-element basis. The smaller element of ``%a`` 13082and ``%b`` at a given index is returned for that index. 13083 13084Arguments: 13085"""""""""" 13086 13087The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13088integer element type. The argument types must match each other, and the return 13089type must match the argument type. 13090 13091 13092'``llvm.umax.*``' Intrinsic 13093^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13094 13095Syntax: 13096""""""" 13097 13098This is an overloaded intrinsic. You can use ``@llvm.umax`` on any 13099integer bit width or any vector of integer elements. 13100 13101:: 13102 13103 declare i32 @llvm.umax.i32(i32 %a, i32 %b) 13104 declare <4 x i32> @llvm.umax.v4i32(<4 x i32> %a, <4 x i32> %b) 13105 13106Overview: 13107""""""""" 13108 13109Return the larger of ``%a`` and ``%b`` comparing the values as unsigned 13110integers. Vector intrinsics operate on a per-element basis. The larger element 13111of ``%a`` and ``%b`` at a given index is returned for that index. 13112 13113Arguments: 13114"""""""""" 13115 13116The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13117integer element type. The argument types must match each other, and the return 13118type must match the argument type. 13119 13120 13121'``llvm.umin.*``' Intrinsic 13122^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13123 13124Syntax: 13125""""""" 13126 13127This is an overloaded intrinsic. You can use ``@llvm.umin`` on any 13128integer bit width or any vector of integer elements. 13129 13130:: 13131 13132 declare i32 @llvm.umin.i32(i32 %a, i32 %b) 13133 declare <4 x i32> @llvm.umin.v4i32(<4 x i32> %a, <4 x i32> %b) 13134 13135Overview: 13136""""""""" 13137 13138Return the smaller of ``%a`` and ``%b`` comparing the values as unsigned 13139integers. Vector intrinsics operate on a per-element basis. The smaller element 13140of ``%a`` and ``%b`` at a given index is returned for that index. 13141 13142Arguments: 13143"""""""""" 13144 13145The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13146integer element type. The argument types must match each other, and the return 13147type must match the argument type. 13148 13149 13150.. _int_memcpy: 13151 13152'``llvm.memcpy``' Intrinsic 13153^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13154 13155Syntax: 13156""""""" 13157 13158This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any 13159integer bit width and for different address spaces. Not all targets 13160support all bit widths however. 13161 13162:: 13163 13164 declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>, 13165 i32 <len>, i1 <isvolatile>) 13166 declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>, 13167 i64 <len>, i1 <isvolatile>) 13168 13169Overview: 13170""""""""" 13171 13172The '``llvm.memcpy.*``' intrinsics copy a block of memory from the 13173source location to the destination location. 13174 13175Note that, unlike the standard libc function, the ``llvm.memcpy.*`` 13176intrinsics do not return a value, takes extra isvolatile 13177arguments and the pointers can be in specified address spaces. 13178 13179Arguments: 13180"""""""""" 13181 13182The first argument is a pointer to the destination, the second is a 13183pointer to the source. The third argument is an integer argument 13184specifying the number of bytes to copy, and the fourth is a 13185boolean indicating a volatile access. 13186 13187The :ref:`align <attr_align>` parameter attribute can be provided 13188for the first and second arguments. 13189 13190If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is 13191a :ref:`volatile operation <volatile>`. The detailed access behavior is not 13192very cleanly specified and it is unwise to depend on it. 13193 13194Semantics: 13195"""""""""" 13196 13197The '``llvm.memcpy.*``' intrinsics copy a block of memory from the source 13198location to the destination location, which must either be equal or 13199non-overlapping. It copies "len" bytes of memory over. If the argument is known 13200to be aligned to some boundary, this can be specified as an attribute on the 13201argument. 13202 13203If ``<len>`` is 0, it is no-op modulo the behavior of attributes attached to 13204the arguments. 13205If ``<len>`` is not a well-defined value, the behavior is undefined. 13206If ``<len>`` is not zero, both ``<dest>`` and ``<src>`` should be well-defined, 13207otherwise the behavior is undefined. 13208 13209.. _int_memcpy_inline: 13210 13211'``llvm.memcpy.inline``' Intrinsic 13212^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13213 13214Syntax: 13215""""""" 13216 13217This is an overloaded intrinsic. You can use ``llvm.memcpy.inline`` on any 13218integer bit width and for different address spaces. Not all targets 13219support all bit widths however. 13220 13221:: 13222 13223 declare void @llvm.memcpy.inline.p0i8.p0i8.i32(i8* <dest>, i8* <src>, 13224 i32 <len>, i1 <isvolatile>) 13225 declare void @llvm.memcpy.inline.p0i8.p0i8.i64(i8* <dest>, i8* <src>, 13226 i64 <len>, i1 <isvolatile>) 13227 13228Overview: 13229""""""""" 13230 13231The '``llvm.memcpy.inline.*``' intrinsics copy a block of memory from the 13232source location to the destination location and guarantees that no external 13233functions are called. 13234 13235Note that, unlike the standard libc function, the ``llvm.memcpy.inline.*`` 13236intrinsics do not return a value, takes extra isvolatile 13237arguments and the pointers can be in specified address spaces. 13238 13239Arguments: 13240"""""""""" 13241 13242The first argument is a pointer to the destination, the second is a 13243pointer to the source. The third argument is a constant integer argument 13244specifying the number of bytes to copy, and the fourth is a 13245boolean indicating a volatile access. 13246 13247The :ref:`align <attr_align>` parameter attribute can be provided 13248for the first and second arguments. 13249 13250If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy.inline`` call is 13251a :ref:`volatile operation <volatile>`. The detailed access behavior is not 13252very cleanly specified and it is unwise to depend on it. 13253 13254Semantics: 13255"""""""""" 13256 13257The '``llvm.memcpy.inline.*``' intrinsics copy a block of memory from the 13258source location to the destination location, which are not allowed to 13259overlap. It copies "len" bytes of memory over. If the argument is known 13260to be aligned to some boundary, this can be specified as an attribute on 13261the argument. 13262The behavior of '``llvm.memcpy.inline.*``' is equivalent to the behavior of 13263'``llvm.memcpy.*``', but the generated code is guaranteed not to call any 13264external functions. 13265 13266.. _int_memmove: 13267 13268'``llvm.memmove``' Intrinsic 13269^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13270 13271Syntax: 13272""""""" 13273 13274This is an overloaded intrinsic. You can use llvm.memmove on any integer 13275bit width and for different address space. Not all targets support all 13276bit widths however. 13277 13278:: 13279 13280 declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>, 13281 i32 <len>, i1 <isvolatile>) 13282 declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>, 13283 i64 <len>, i1 <isvolatile>) 13284 13285Overview: 13286""""""""" 13287 13288The '``llvm.memmove.*``' intrinsics move a block of memory from the 13289source location to the destination location. It is similar to the 13290'``llvm.memcpy``' intrinsic but allows the two memory locations to 13291overlap. 13292 13293Note that, unlike the standard libc function, the ``llvm.memmove.*`` 13294intrinsics do not return a value, takes an extra isvolatile 13295argument and the pointers can be in specified address spaces. 13296 13297Arguments: 13298"""""""""" 13299 13300The first argument is a pointer to the destination, the second is a 13301pointer to the source. The third argument is an integer argument 13302specifying the number of bytes to copy, and the fourth is a 13303boolean indicating a volatile access. 13304 13305The :ref:`align <attr_align>` parameter attribute can be provided 13306for the first and second arguments. 13307 13308If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call 13309is a :ref:`volatile operation <volatile>`. The detailed access behavior is 13310not very cleanly specified and it is unwise to depend on it. 13311 13312Semantics: 13313"""""""""" 13314 13315The '``llvm.memmove.*``' intrinsics copy a block of memory from the 13316source location to the destination location, which may overlap. It 13317copies "len" bytes of memory over. If the argument is known to be 13318aligned to some boundary, this can be specified as an attribute on 13319the argument. 13320 13321If ``<len>`` is 0, it is no-op modulo the behavior of attributes attached to 13322the arguments. 13323If ``<len>`` is not a well-defined value, the behavior is undefined. 13324If ``<len>`` is not zero, both ``<dest>`` and ``<src>`` should be well-defined, 13325otherwise the behavior is undefined. 13326 13327.. _int_memset: 13328 13329'``llvm.memset.*``' Intrinsics 13330^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13331 13332Syntax: 13333""""""" 13334 13335This is an overloaded intrinsic. You can use llvm.memset on any integer 13336bit width and for different address spaces. However, not all targets 13337support all bit widths. 13338 13339:: 13340 13341 declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>, 13342 i32 <len>, i1 <isvolatile>) 13343 declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>, 13344 i64 <len>, i1 <isvolatile>) 13345 13346Overview: 13347""""""""" 13348 13349The '``llvm.memset.*``' intrinsics fill a block of memory with a 13350particular byte value. 13351 13352Note that, unlike the standard libc function, the ``llvm.memset`` 13353intrinsic does not return a value and takes an extra volatile 13354argument. Also, the destination can be in an arbitrary address space. 13355 13356Arguments: 13357"""""""""" 13358 13359The first argument is a pointer to the destination to fill, the second 13360is the byte value with which to fill it, the third argument is an 13361integer argument specifying the number of bytes to fill, and the fourth 13362is a boolean indicating a volatile access. 13363 13364The :ref:`align <attr_align>` parameter attribute can be provided 13365for the first arguments. 13366 13367If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is 13368a :ref:`volatile operation <volatile>`. The detailed access behavior is not 13369very cleanly specified and it is unwise to depend on it. 13370 13371Semantics: 13372"""""""""" 13373 13374The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting 13375at the destination location. If the argument is known to be 13376aligned to some boundary, this can be specified as an attribute on 13377the argument. 13378 13379If ``<len>`` is 0, it is no-op modulo the behavior of attributes attached to 13380the arguments. 13381If ``<len>`` is not a well-defined value, the behavior is undefined. 13382If ``<len>`` is not zero, both ``<dest>`` and ``<src>`` should be well-defined, 13383otherwise the behavior is undefined. 13384 13385'``llvm.sqrt.*``' Intrinsic 13386^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13387 13388Syntax: 13389""""""" 13390 13391This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any 13392floating-point or vector of floating-point type. Not all targets support 13393all types however. 13394 13395:: 13396 13397 declare float @llvm.sqrt.f32(float %Val) 13398 declare double @llvm.sqrt.f64(double %Val) 13399 declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val) 13400 declare fp128 @llvm.sqrt.f128(fp128 %Val) 13401 declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val) 13402 13403Overview: 13404""""""""" 13405 13406The '``llvm.sqrt``' intrinsics return the square root of the specified value. 13407 13408Arguments: 13409"""""""""" 13410 13411The argument and return value are floating-point numbers of the same type. 13412 13413Semantics: 13414"""""""""" 13415 13416Return the same value as a corresponding libm '``sqrt``' function but without 13417trapping or setting ``errno``. For types specified by IEEE-754, the result 13418matches a conforming libm implementation. 13419 13420When specified with the fast-math-flag 'afn', the result may be approximated 13421using a less accurate calculation. 13422 13423'``llvm.powi.*``' Intrinsic 13424^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13425 13426Syntax: 13427""""""" 13428 13429This is an overloaded intrinsic. You can use ``llvm.powi`` on any 13430floating-point or vector of floating-point type. Not all targets support 13431all types however. 13432 13433:: 13434 13435 declare float @llvm.powi.f32(float %Val, i32 %power) 13436 declare double @llvm.powi.f64(double %Val, i32 %power) 13437 declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power) 13438 declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power) 13439 declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power) 13440 13441Overview: 13442""""""""" 13443 13444The '``llvm.powi.*``' intrinsics return the first operand raised to the 13445specified (positive or negative) power. The order of evaluation of 13446multiplications is not defined. When a vector of floating-point type is 13447used, the second argument remains a scalar integer value. 13448 13449Arguments: 13450"""""""""" 13451 13452The second argument is an integer power, and the first is a value to 13453raise to that power. 13454 13455Semantics: 13456"""""""""" 13457 13458This function returns the first value raised to the second power with an 13459unspecified sequence of rounding operations. 13460 13461'``llvm.sin.*``' Intrinsic 13462^^^^^^^^^^^^^^^^^^^^^^^^^^ 13463 13464Syntax: 13465""""""" 13466 13467This is an overloaded intrinsic. You can use ``llvm.sin`` on any 13468floating-point or vector of floating-point type. Not all targets support 13469all types however. 13470 13471:: 13472 13473 declare float @llvm.sin.f32(float %Val) 13474 declare double @llvm.sin.f64(double %Val) 13475 declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val) 13476 declare fp128 @llvm.sin.f128(fp128 %Val) 13477 declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val) 13478 13479Overview: 13480""""""""" 13481 13482The '``llvm.sin.*``' intrinsics return the sine of the operand. 13483 13484Arguments: 13485"""""""""" 13486 13487The argument and return value are floating-point numbers of the same type. 13488 13489Semantics: 13490"""""""""" 13491 13492Return the same value as a corresponding libm '``sin``' function but without 13493trapping or setting ``errno``. 13494 13495When specified with the fast-math-flag 'afn', the result may be approximated 13496using a less accurate calculation. 13497 13498'``llvm.cos.*``' Intrinsic 13499^^^^^^^^^^^^^^^^^^^^^^^^^^ 13500 13501Syntax: 13502""""""" 13503 13504This is an overloaded intrinsic. You can use ``llvm.cos`` on any 13505floating-point or vector of floating-point type. Not all targets support 13506all types however. 13507 13508:: 13509 13510 declare float @llvm.cos.f32(float %Val) 13511 declare double @llvm.cos.f64(double %Val) 13512 declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val) 13513 declare fp128 @llvm.cos.f128(fp128 %Val) 13514 declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val) 13515 13516Overview: 13517""""""""" 13518 13519The '``llvm.cos.*``' intrinsics return the cosine of the operand. 13520 13521Arguments: 13522"""""""""" 13523 13524The argument and return value are floating-point numbers of the same type. 13525 13526Semantics: 13527"""""""""" 13528 13529Return the same value as a corresponding libm '``cos``' function but without 13530trapping or setting ``errno``. 13531 13532When specified with the fast-math-flag 'afn', the result may be approximated 13533using a less accurate calculation. 13534 13535'``llvm.pow.*``' Intrinsic 13536^^^^^^^^^^^^^^^^^^^^^^^^^^ 13537 13538Syntax: 13539""""""" 13540 13541This is an overloaded intrinsic. You can use ``llvm.pow`` on any 13542floating-point or vector of floating-point type. Not all targets support 13543all types however. 13544 13545:: 13546 13547 declare float @llvm.pow.f32(float %Val, float %Power) 13548 declare double @llvm.pow.f64(double %Val, double %Power) 13549 declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power) 13550 declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power) 13551 declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power) 13552 13553Overview: 13554""""""""" 13555 13556The '``llvm.pow.*``' intrinsics return the first operand raised to the 13557specified (positive or negative) power. 13558 13559Arguments: 13560"""""""""" 13561 13562The arguments and return value are floating-point numbers of the same type. 13563 13564Semantics: 13565"""""""""" 13566 13567Return the same value as a corresponding libm '``pow``' function but without 13568trapping or setting ``errno``. 13569 13570When specified with the fast-math-flag 'afn', the result may be approximated 13571using a less accurate calculation. 13572 13573'``llvm.exp.*``' Intrinsic 13574^^^^^^^^^^^^^^^^^^^^^^^^^^ 13575 13576Syntax: 13577""""""" 13578 13579This is an overloaded intrinsic. You can use ``llvm.exp`` on any 13580floating-point or vector of floating-point type. Not all targets support 13581all types however. 13582 13583:: 13584 13585 declare float @llvm.exp.f32(float %Val) 13586 declare double @llvm.exp.f64(double %Val) 13587 declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val) 13588 declare fp128 @llvm.exp.f128(fp128 %Val) 13589 declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val) 13590 13591Overview: 13592""""""""" 13593 13594The '``llvm.exp.*``' intrinsics compute the base-e exponential of the specified 13595value. 13596 13597Arguments: 13598"""""""""" 13599 13600The argument and return value are floating-point numbers of the same type. 13601 13602Semantics: 13603"""""""""" 13604 13605Return the same value as a corresponding libm '``exp``' function but without 13606trapping or setting ``errno``. 13607 13608When specified with the fast-math-flag 'afn', the result may be approximated 13609using a less accurate calculation. 13610 13611'``llvm.exp2.*``' Intrinsic 13612^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13613 13614Syntax: 13615""""""" 13616 13617This is an overloaded intrinsic. You can use ``llvm.exp2`` on any 13618floating-point or vector of floating-point type. Not all targets support 13619all types however. 13620 13621:: 13622 13623 declare float @llvm.exp2.f32(float %Val) 13624 declare double @llvm.exp2.f64(double %Val) 13625 declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val) 13626 declare fp128 @llvm.exp2.f128(fp128 %Val) 13627 declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val) 13628 13629Overview: 13630""""""""" 13631 13632The '``llvm.exp2.*``' intrinsics compute the base-2 exponential of the 13633specified value. 13634 13635Arguments: 13636"""""""""" 13637 13638The argument and return value are floating-point numbers of the same type. 13639 13640Semantics: 13641"""""""""" 13642 13643Return the same value as a corresponding libm '``exp2``' function but without 13644trapping or setting ``errno``. 13645 13646When specified with the fast-math-flag 'afn', the result may be approximated 13647using a less accurate calculation. 13648 13649'``llvm.log.*``' Intrinsic 13650^^^^^^^^^^^^^^^^^^^^^^^^^^ 13651 13652Syntax: 13653""""""" 13654 13655This is an overloaded intrinsic. You can use ``llvm.log`` on any 13656floating-point or vector of floating-point type. Not all targets support 13657all types however. 13658 13659:: 13660 13661 declare float @llvm.log.f32(float %Val) 13662 declare double @llvm.log.f64(double %Val) 13663 declare x86_fp80 @llvm.log.f80(x86_fp80 %Val) 13664 declare fp128 @llvm.log.f128(fp128 %Val) 13665 declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val) 13666 13667Overview: 13668""""""""" 13669 13670The '``llvm.log.*``' intrinsics compute the base-e logarithm of the specified 13671value. 13672 13673Arguments: 13674"""""""""" 13675 13676The argument and return value are floating-point numbers of the same type. 13677 13678Semantics: 13679"""""""""" 13680 13681Return the same value as a corresponding libm '``log``' function but without 13682trapping or setting ``errno``. 13683 13684When specified with the fast-math-flag 'afn', the result may be approximated 13685using a less accurate calculation. 13686 13687'``llvm.log10.*``' Intrinsic 13688^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13689 13690Syntax: 13691""""""" 13692 13693This is an overloaded intrinsic. You can use ``llvm.log10`` on any 13694floating-point or vector of floating-point type. Not all targets support 13695all types however. 13696 13697:: 13698 13699 declare float @llvm.log10.f32(float %Val) 13700 declare double @llvm.log10.f64(double %Val) 13701 declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val) 13702 declare fp128 @llvm.log10.f128(fp128 %Val) 13703 declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val) 13704 13705Overview: 13706""""""""" 13707 13708The '``llvm.log10.*``' intrinsics compute the base-10 logarithm of the 13709specified value. 13710 13711Arguments: 13712"""""""""" 13713 13714The argument and return value are floating-point numbers of the same type. 13715 13716Semantics: 13717"""""""""" 13718 13719Return the same value as a corresponding libm '``log10``' function but without 13720trapping or setting ``errno``. 13721 13722When specified with the fast-math-flag 'afn', the result may be approximated 13723using a less accurate calculation. 13724 13725'``llvm.log2.*``' Intrinsic 13726^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13727 13728Syntax: 13729""""""" 13730 13731This is an overloaded intrinsic. You can use ``llvm.log2`` on any 13732floating-point or vector of floating-point type. Not all targets support 13733all types however. 13734 13735:: 13736 13737 declare float @llvm.log2.f32(float %Val) 13738 declare double @llvm.log2.f64(double %Val) 13739 declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val) 13740 declare fp128 @llvm.log2.f128(fp128 %Val) 13741 declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val) 13742 13743Overview: 13744""""""""" 13745 13746The '``llvm.log2.*``' intrinsics compute the base-2 logarithm of the specified 13747value. 13748 13749Arguments: 13750"""""""""" 13751 13752The argument and return value are floating-point numbers of the same type. 13753 13754Semantics: 13755"""""""""" 13756 13757Return the same value as a corresponding libm '``log2``' function but without 13758trapping or setting ``errno``. 13759 13760When specified with the fast-math-flag 'afn', the result may be approximated 13761using a less accurate calculation. 13762 13763.. _int_fma: 13764 13765'``llvm.fma.*``' Intrinsic 13766^^^^^^^^^^^^^^^^^^^^^^^^^^ 13767 13768Syntax: 13769""""""" 13770 13771This is an overloaded intrinsic. You can use ``llvm.fma`` on any 13772floating-point or vector of floating-point type. Not all targets support 13773all types however. 13774 13775:: 13776 13777 declare float @llvm.fma.f32(float %a, float %b, float %c) 13778 declare double @llvm.fma.f64(double %a, double %b, double %c) 13779 declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c) 13780 declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c) 13781 declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c) 13782 13783Overview: 13784""""""""" 13785 13786The '``llvm.fma.*``' intrinsics perform the fused multiply-add operation. 13787 13788Arguments: 13789"""""""""" 13790 13791The arguments and return value are floating-point numbers of the same type. 13792 13793Semantics: 13794"""""""""" 13795 13796Return the same value as a corresponding libm '``fma``' function but without 13797trapping or setting ``errno``. 13798 13799When specified with the fast-math-flag 'afn', the result may be approximated 13800using a less accurate calculation. 13801 13802'``llvm.fabs.*``' Intrinsic 13803^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13804 13805Syntax: 13806""""""" 13807 13808This is an overloaded intrinsic. You can use ``llvm.fabs`` on any 13809floating-point or vector of floating-point type. Not all targets support 13810all types however. 13811 13812:: 13813 13814 declare float @llvm.fabs.f32(float %Val) 13815 declare double @llvm.fabs.f64(double %Val) 13816 declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val) 13817 declare fp128 @llvm.fabs.f128(fp128 %Val) 13818 declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val) 13819 13820Overview: 13821""""""""" 13822 13823The '``llvm.fabs.*``' intrinsics return the absolute value of the 13824operand. 13825 13826Arguments: 13827"""""""""" 13828 13829The argument and return value are floating-point numbers of the same 13830type. 13831 13832Semantics: 13833"""""""""" 13834 13835This function returns the same values as the libm ``fabs`` functions 13836would, and handles error conditions in the same way. 13837 13838'``llvm.minnum.*``' Intrinsic 13839^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13840 13841Syntax: 13842""""""" 13843 13844This is an overloaded intrinsic. You can use ``llvm.minnum`` on any 13845floating-point or vector of floating-point type. Not all targets support 13846all types however. 13847 13848:: 13849 13850 declare float @llvm.minnum.f32(float %Val0, float %Val1) 13851 declare double @llvm.minnum.f64(double %Val0, double %Val1) 13852 declare x86_fp80 @llvm.minnum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 13853 declare fp128 @llvm.minnum.f128(fp128 %Val0, fp128 %Val1) 13854 declare ppc_fp128 @llvm.minnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 13855 13856Overview: 13857""""""""" 13858 13859The '``llvm.minnum.*``' intrinsics return the minimum of the two 13860arguments. 13861 13862 13863Arguments: 13864"""""""""" 13865 13866The arguments and return value are floating-point numbers of the same 13867type. 13868 13869Semantics: 13870"""""""""" 13871 13872Follows the IEEE-754 semantics for minNum, except for handling of 13873signaling NaNs. This match's the behavior of libm's fmin. 13874 13875If either operand is a NaN, returns the other non-NaN operand. Returns 13876NaN only if both operands are NaN. The returned NaN is always 13877quiet. If the operands compare equal, returns a value that compares 13878equal to both operands. This means that fmin(+/-0.0, +/-0.0) could 13879return either -0.0 or 0.0. 13880 13881Unlike the IEEE-754 2008 behavior, this does not distinguish between 13882signaling and quiet NaN inputs. If a target's implementation follows 13883the standard and returns a quiet NaN if either input is a signaling 13884NaN, the intrinsic lowering is responsible for quieting the inputs to 13885correctly return the non-NaN input (e.g. by using the equivalent of 13886``llvm.canonicalize``). 13887 13888 13889'``llvm.maxnum.*``' Intrinsic 13890^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13891 13892Syntax: 13893""""""" 13894 13895This is an overloaded intrinsic. You can use ``llvm.maxnum`` on any 13896floating-point or vector of floating-point type. Not all targets support 13897all types however. 13898 13899:: 13900 13901 declare float @llvm.maxnum.f32(float %Val0, float %Val1l) 13902 declare double @llvm.maxnum.f64(double %Val0, double %Val1) 13903 declare x86_fp80 @llvm.maxnum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 13904 declare fp128 @llvm.maxnum.f128(fp128 %Val0, fp128 %Val1) 13905 declare ppc_fp128 @llvm.maxnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 13906 13907Overview: 13908""""""""" 13909 13910The '``llvm.maxnum.*``' intrinsics return the maximum of the two 13911arguments. 13912 13913 13914Arguments: 13915"""""""""" 13916 13917The arguments and return value are floating-point numbers of the same 13918type. 13919 13920Semantics: 13921"""""""""" 13922Follows the IEEE-754 semantics for maxNum except for the handling of 13923signaling NaNs. This matches the behavior of libm's fmax. 13924 13925If either operand is a NaN, returns the other non-NaN operand. Returns 13926NaN only if both operands are NaN. The returned NaN is always 13927quiet. If the operands compare equal, returns a value that compares 13928equal to both operands. This means that fmax(+/-0.0, +/-0.0) could 13929return either -0.0 or 0.0. 13930 13931Unlike the IEEE-754 2008 behavior, this does not distinguish between 13932signaling and quiet NaN inputs. If a target's implementation follows 13933the standard and returns a quiet NaN if either input is a signaling 13934NaN, the intrinsic lowering is responsible for quieting the inputs to 13935correctly return the non-NaN input (e.g. by using the equivalent of 13936``llvm.canonicalize``). 13937 13938'``llvm.minimum.*``' Intrinsic 13939^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13940 13941Syntax: 13942""""""" 13943 13944This is an overloaded intrinsic. You can use ``llvm.minimum`` on any 13945floating-point or vector of floating-point type. Not all targets support 13946all types however. 13947 13948:: 13949 13950 declare float @llvm.minimum.f32(float %Val0, float %Val1) 13951 declare double @llvm.minimum.f64(double %Val0, double %Val1) 13952 declare x86_fp80 @llvm.minimum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 13953 declare fp128 @llvm.minimum.f128(fp128 %Val0, fp128 %Val1) 13954 declare ppc_fp128 @llvm.minimum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 13955 13956Overview: 13957""""""""" 13958 13959The '``llvm.minimum.*``' intrinsics return the minimum of the two 13960arguments, propagating NaNs and treating -0.0 as less than +0.0. 13961 13962 13963Arguments: 13964"""""""""" 13965 13966The arguments and return value are floating-point numbers of the same 13967type. 13968 13969Semantics: 13970"""""""""" 13971If either operand is a NaN, returns NaN. Otherwise returns the lesser 13972of the two arguments. -0.0 is considered to be less than +0.0 for this 13973intrinsic. Note that these are the semantics specified in the draft of 13974IEEE 754-2018. 13975 13976'``llvm.maximum.*``' Intrinsic 13977^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13978 13979Syntax: 13980""""""" 13981 13982This is an overloaded intrinsic. You can use ``llvm.maximum`` on any 13983floating-point or vector of floating-point type. Not all targets support 13984all types however. 13985 13986:: 13987 13988 declare float @llvm.maximum.f32(float %Val0, float %Val1) 13989 declare double @llvm.maximum.f64(double %Val0, double %Val1) 13990 declare x86_fp80 @llvm.maximum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 13991 declare fp128 @llvm.maximum.f128(fp128 %Val0, fp128 %Val1) 13992 declare ppc_fp128 @llvm.maximum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 13993 13994Overview: 13995""""""""" 13996 13997The '``llvm.maximum.*``' intrinsics return the maximum of the two 13998arguments, propagating NaNs and treating -0.0 as less than +0.0. 13999 14000 14001Arguments: 14002"""""""""" 14003 14004The arguments and return value are floating-point numbers of the same 14005type. 14006 14007Semantics: 14008"""""""""" 14009If either operand is a NaN, returns NaN. Otherwise returns the greater 14010of the two arguments. -0.0 is considered to be less than +0.0 for this 14011intrinsic. Note that these are the semantics specified in the draft of 14012IEEE 754-2018. 14013 14014'``llvm.copysign.*``' Intrinsic 14015^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14016 14017Syntax: 14018""""""" 14019 14020This is an overloaded intrinsic. You can use ``llvm.copysign`` on any 14021floating-point or vector of floating-point type. Not all targets support 14022all types however. 14023 14024:: 14025 14026 declare float @llvm.copysign.f32(float %Mag, float %Sgn) 14027 declare double @llvm.copysign.f64(double %Mag, double %Sgn) 14028 declare x86_fp80 @llvm.copysign.f80(x86_fp80 %Mag, x86_fp80 %Sgn) 14029 declare fp128 @llvm.copysign.f128(fp128 %Mag, fp128 %Sgn) 14030 declare ppc_fp128 @llvm.copysign.ppcf128(ppc_fp128 %Mag, ppc_fp128 %Sgn) 14031 14032Overview: 14033""""""""" 14034 14035The '``llvm.copysign.*``' intrinsics return a value with the magnitude of the 14036first operand and the sign of the second operand. 14037 14038Arguments: 14039"""""""""" 14040 14041The arguments and return value are floating-point numbers of the same 14042type. 14043 14044Semantics: 14045"""""""""" 14046 14047This function returns the same values as the libm ``copysign`` 14048functions would, and handles error conditions in the same way. 14049 14050'``llvm.floor.*``' Intrinsic 14051^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14052 14053Syntax: 14054""""""" 14055 14056This is an overloaded intrinsic. You can use ``llvm.floor`` on any 14057floating-point or vector of floating-point type. Not all targets support 14058all types however. 14059 14060:: 14061 14062 declare float @llvm.floor.f32(float %Val) 14063 declare double @llvm.floor.f64(double %Val) 14064 declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val) 14065 declare fp128 @llvm.floor.f128(fp128 %Val) 14066 declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val) 14067 14068Overview: 14069""""""""" 14070 14071The '``llvm.floor.*``' intrinsics return the floor of the operand. 14072 14073Arguments: 14074"""""""""" 14075 14076The argument and return value are floating-point numbers of the same 14077type. 14078 14079Semantics: 14080"""""""""" 14081 14082This function returns the same values as the libm ``floor`` functions 14083would, and handles error conditions in the same way. 14084 14085'``llvm.ceil.*``' Intrinsic 14086^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14087 14088Syntax: 14089""""""" 14090 14091This is an overloaded intrinsic. You can use ``llvm.ceil`` on any 14092floating-point or vector of floating-point type. Not all targets support 14093all types however. 14094 14095:: 14096 14097 declare float @llvm.ceil.f32(float %Val) 14098 declare double @llvm.ceil.f64(double %Val) 14099 declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val) 14100 declare fp128 @llvm.ceil.f128(fp128 %Val) 14101 declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val) 14102 14103Overview: 14104""""""""" 14105 14106The '``llvm.ceil.*``' intrinsics return the ceiling of the operand. 14107 14108Arguments: 14109"""""""""" 14110 14111The argument and return value are floating-point numbers of the same 14112type. 14113 14114Semantics: 14115"""""""""" 14116 14117This function returns the same values as the libm ``ceil`` functions 14118would, and handles error conditions in the same way. 14119 14120'``llvm.trunc.*``' Intrinsic 14121^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14122 14123Syntax: 14124""""""" 14125 14126This is an overloaded intrinsic. You can use ``llvm.trunc`` on any 14127floating-point or vector of floating-point type. Not all targets support 14128all types however. 14129 14130:: 14131 14132 declare float @llvm.trunc.f32(float %Val) 14133 declare double @llvm.trunc.f64(double %Val) 14134 declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val) 14135 declare fp128 @llvm.trunc.f128(fp128 %Val) 14136 declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val) 14137 14138Overview: 14139""""""""" 14140 14141The '``llvm.trunc.*``' intrinsics returns the operand rounded to the 14142nearest integer not larger in magnitude than the operand. 14143 14144Arguments: 14145"""""""""" 14146 14147The argument and return value are floating-point numbers of the same 14148type. 14149 14150Semantics: 14151"""""""""" 14152 14153This function returns the same values as the libm ``trunc`` functions 14154would, and handles error conditions in the same way. 14155 14156'``llvm.rint.*``' Intrinsic 14157^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14158 14159Syntax: 14160""""""" 14161 14162This is an overloaded intrinsic. You can use ``llvm.rint`` on any 14163floating-point or vector of floating-point type. Not all targets support 14164all types however. 14165 14166:: 14167 14168 declare float @llvm.rint.f32(float %Val) 14169 declare double @llvm.rint.f64(double %Val) 14170 declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val) 14171 declare fp128 @llvm.rint.f128(fp128 %Val) 14172 declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val) 14173 14174Overview: 14175""""""""" 14176 14177The '``llvm.rint.*``' intrinsics returns the operand rounded to the 14178nearest integer. It may raise an inexact floating-point exception if the 14179operand isn't an integer. 14180 14181Arguments: 14182"""""""""" 14183 14184The argument and return value are floating-point numbers of the same 14185type. 14186 14187Semantics: 14188"""""""""" 14189 14190This function returns the same values as the libm ``rint`` functions 14191would, and handles error conditions in the same way. 14192 14193'``llvm.nearbyint.*``' Intrinsic 14194^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14195 14196Syntax: 14197""""""" 14198 14199This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any 14200floating-point or vector of floating-point type. Not all targets support 14201all types however. 14202 14203:: 14204 14205 declare float @llvm.nearbyint.f32(float %Val) 14206 declare double @llvm.nearbyint.f64(double %Val) 14207 declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val) 14208 declare fp128 @llvm.nearbyint.f128(fp128 %Val) 14209 declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val) 14210 14211Overview: 14212""""""""" 14213 14214The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the 14215nearest integer. 14216 14217Arguments: 14218"""""""""" 14219 14220The argument and return value are floating-point numbers of the same 14221type. 14222 14223Semantics: 14224"""""""""" 14225 14226This function returns the same values as the libm ``nearbyint`` 14227functions would, and handles error conditions in the same way. 14228 14229'``llvm.round.*``' Intrinsic 14230^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14231 14232Syntax: 14233""""""" 14234 14235This is an overloaded intrinsic. You can use ``llvm.round`` on any 14236floating-point or vector of floating-point type. Not all targets support 14237all types however. 14238 14239:: 14240 14241 declare float @llvm.round.f32(float %Val) 14242 declare double @llvm.round.f64(double %Val) 14243 declare x86_fp80 @llvm.round.f80(x86_fp80 %Val) 14244 declare fp128 @llvm.round.f128(fp128 %Val) 14245 declare ppc_fp128 @llvm.round.ppcf128(ppc_fp128 %Val) 14246 14247Overview: 14248""""""""" 14249 14250The '``llvm.round.*``' intrinsics returns the operand rounded to the 14251nearest integer. 14252 14253Arguments: 14254"""""""""" 14255 14256The argument and return value are floating-point numbers of the same 14257type. 14258 14259Semantics: 14260"""""""""" 14261 14262This function returns the same values as the libm ``round`` 14263functions would, and handles error conditions in the same way. 14264 14265'``llvm.roundeven.*``' Intrinsic 14266^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14267 14268Syntax: 14269""""""" 14270 14271This is an overloaded intrinsic. You can use ``llvm.roundeven`` on any 14272floating-point or vector of floating-point type. Not all targets support 14273all types however. 14274 14275:: 14276 14277 declare float @llvm.roundeven.f32(float %Val) 14278 declare double @llvm.roundeven.f64(double %Val) 14279 declare x86_fp80 @llvm.roundeven.f80(x86_fp80 %Val) 14280 declare fp128 @llvm.roundeven.f128(fp128 %Val) 14281 declare ppc_fp128 @llvm.roundeven.ppcf128(ppc_fp128 %Val) 14282 14283Overview: 14284""""""""" 14285 14286The '``llvm.roundeven.*``' intrinsics returns the operand rounded to the nearest 14287integer in floating-point format rounding halfway cases to even (that is, to the 14288nearest value that is an even integer). 14289 14290Arguments: 14291"""""""""" 14292 14293The argument and return value are floating-point numbers of the same type. 14294 14295Semantics: 14296"""""""""" 14297 14298This function implements IEEE-754 operation ``roundToIntegralTiesToEven``. It 14299also behaves in the same way as C standard function ``roundeven``, except that 14300it does not raise floating point exceptions. 14301 14302 14303'``llvm.lround.*``' Intrinsic 14304^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14305 14306Syntax: 14307""""""" 14308 14309This is an overloaded intrinsic. You can use ``llvm.lround`` on any 14310floating-point type. Not all targets support all types however. 14311 14312:: 14313 14314 declare i32 @llvm.lround.i32.f32(float %Val) 14315 declare i32 @llvm.lround.i32.f64(double %Val) 14316 declare i32 @llvm.lround.i32.f80(float %Val) 14317 declare i32 @llvm.lround.i32.f128(double %Val) 14318 declare i32 @llvm.lround.i32.ppcf128(double %Val) 14319 14320 declare i64 @llvm.lround.i64.f32(float %Val) 14321 declare i64 @llvm.lround.i64.f64(double %Val) 14322 declare i64 @llvm.lround.i64.f80(float %Val) 14323 declare i64 @llvm.lround.i64.f128(double %Val) 14324 declare i64 @llvm.lround.i64.ppcf128(double %Val) 14325 14326Overview: 14327""""""""" 14328 14329The '``llvm.lround.*``' intrinsics return the operand rounded to the nearest 14330integer with ties away from zero. 14331 14332 14333Arguments: 14334"""""""""" 14335 14336The argument is a floating-point number and the return value is an integer 14337type. 14338 14339Semantics: 14340"""""""""" 14341 14342This function returns the same values as the libm ``lround`` 14343functions would, but without setting errno. 14344 14345'``llvm.llround.*``' Intrinsic 14346^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14347 14348Syntax: 14349""""""" 14350 14351This is an overloaded intrinsic. You can use ``llvm.llround`` on any 14352floating-point type. Not all targets support all types however. 14353 14354:: 14355 14356 declare i64 @llvm.lround.i64.f32(float %Val) 14357 declare i64 @llvm.lround.i64.f64(double %Val) 14358 declare i64 @llvm.lround.i64.f80(float %Val) 14359 declare i64 @llvm.lround.i64.f128(double %Val) 14360 declare i64 @llvm.lround.i64.ppcf128(double %Val) 14361 14362Overview: 14363""""""""" 14364 14365The '``llvm.llround.*``' intrinsics return the operand rounded to the nearest 14366integer with ties away from zero. 14367 14368Arguments: 14369"""""""""" 14370 14371The argument is a floating-point number and the return value is an integer 14372type. 14373 14374Semantics: 14375"""""""""" 14376 14377This function returns the same values as the libm ``llround`` 14378functions would, but without setting errno. 14379 14380'``llvm.lrint.*``' Intrinsic 14381^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14382 14383Syntax: 14384""""""" 14385 14386This is an overloaded intrinsic. You can use ``llvm.lrint`` on any 14387floating-point type. Not all targets support all types however. 14388 14389:: 14390 14391 declare i32 @llvm.lrint.i32.f32(float %Val) 14392 declare i32 @llvm.lrint.i32.f64(double %Val) 14393 declare i32 @llvm.lrint.i32.f80(float %Val) 14394 declare i32 @llvm.lrint.i32.f128(double %Val) 14395 declare i32 @llvm.lrint.i32.ppcf128(double %Val) 14396 14397 declare i64 @llvm.lrint.i64.f32(float %Val) 14398 declare i64 @llvm.lrint.i64.f64(double %Val) 14399 declare i64 @llvm.lrint.i64.f80(float %Val) 14400 declare i64 @llvm.lrint.i64.f128(double %Val) 14401 declare i64 @llvm.lrint.i64.ppcf128(double %Val) 14402 14403Overview: 14404""""""""" 14405 14406The '``llvm.lrint.*``' intrinsics return the operand rounded to the nearest 14407integer. 14408 14409 14410Arguments: 14411"""""""""" 14412 14413The argument is a floating-point number and the return value is an integer 14414type. 14415 14416Semantics: 14417"""""""""" 14418 14419This function returns the same values as the libm ``lrint`` 14420functions would, but without setting errno. 14421 14422'``llvm.llrint.*``' Intrinsic 14423^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14424 14425Syntax: 14426""""""" 14427 14428This is an overloaded intrinsic. You can use ``llvm.llrint`` on any 14429floating-point type. Not all targets support all types however. 14430 14431:: 14432 14433 declare i64 @llvm.llrint.i64.f32(float %Val) 14434 declare i64 @llvm.llrint.i64.f64(double %Val) 14435 declare i64 @llvm.llrint.i64.f80(float %Val) 14436 declare i64 @llvm.llrint.i64.f128(double %Val) 14437 declare i64 @llvm.llrint.i64.ppcf128(double %Val) 14438 14439Overview: 14440""""""""" 14441 14442The '``llvm.llrint.*``' intrinsics return the operand rounded to the nearest 14443integer. 14444 14445Arguments: 14446"""""""""" 14447 14448The argument is a floating-point number and the return value is an integer 14449type. 14450 14451Semantics: 14452"""""""""" 14453 14454This function returns the same values as the libm ``llrint`` 14455functions would, but without setting errno. 14456 14457Bit Manipulation Intrinsics 14458--------------------------- 14459 14460LLVM provides intrinsics for a few important bit manipulation 14461operations. These allow efficient code generation for some algorithms. 14462 14463'``llvm.bitreverse.*``' Intrinsics 14464^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14465 14466Syntax: 14467""""""" 14468 14469This is an overloaded intrinsic function. You can use bitreverse on any 14470integer type. 14471 14472:: 14473 14474 declare i16 @llvm.bitreverse.i16(i16 <id>) 14475 declare i32 @llvm.bitreverse.i32(i32 <id>) 14476 declare i64 @llvm.bitreverse.i64(i64 <id>) 14477 declare <4 x i32> @llvm.bitreverse.v4i32(<4 x i32> <id>) 14478 14479Overview: 14480""""""""" 14481 14482The '``llvm.bitreverse``' family of intrinsics is used to reverse the 14483bitpattern of an integer value or vector of integer values; for example 14484``0b10110110`` becomes ``0b01101101``. 14485 14486Semantics: 14487"""""""""" 14488 14489The ``llvm.bitreverse.iN`` intrinsic returns an iN value that has bit 14490``M`` in the input moved to bit ``N-M`` in the output. The vector 14491intrinsics, such as ``llvm.bitreverse.v4i32``, operate on a per-element 14492basis and the element order is not affected. 14493 14494'``llvm.bswap.*``' Intrinsics 14495^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14496 14497Syntax: 14498""""""" 14499 14500This is an overloaded intrinsic function. You can use bswap on any 14501integer type that is an even number of bytes (i.e. BitWidth % 16 == 0). 14502 14503:: 14504 14505 declare i16 @llvm.bswap.i16(i16 <id>) 14506 declare i32 @llvm.bswap.i32(i32 <id>) 14507 declare i64 @llvm.bswap.i64(i64 <id>) 14508 declare <4 x i32> @llvm.bswap.v4i32(<4 x i32> <id>) 14509 14510Overview: 14511""""""""" 14512 14513The '``llvm.bswap``' family of intrinsics is used to byte swap an integer 14514value or vector of integer values with an even number of bytes (positive 14515multiple of 16 bits). 14516 14517Semantics: 14518"""""""""" 14519 14520The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high 14521and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32`` 14522intrinsic returns an i32 value that has the four bytes of the input i32 14523swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the 14524returned i32 will have its bytes in 3, 2, 1, 0 order. The 14525``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this 14526concept to additional even-byte lengths (6 bytes, 8 bytes and more, 14527respectively). The vector intrinsics, such as ``llvm.bswap.v4i32``, 14528operate on a per-element basis and the element order is not affected. 14529 14530'``llvm.ctpop.*``' Intrinsic 14531^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14532 14533Syntax: 14534""""""" 14535 14536This is an overloaded intrinsic. You can use llvm.ctpop on any integer 14537bit width, or on any vector with integer elements. Not all targets 14538support all bit widths or vector types, however. 14539 14540:: 14541 14542 declare i8 @llvm.ctpop.i8(i8 <src>) 14543 declare i16 @llvm.ctpop.i16(i16 <src>) 14544 declare i32 @llvm.ctpop.i32(i32 <src>) 14545 declare i64 @llvm.ctpop.i64(i64 <src>) 14546 declare i256 @llvm.ctpop.i256(i256 <src>) 14547 declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>) 14548 14549Overview: 14550""""""""" 14551 14552The '``llvm.ctpop``' family of intrinsics counts the number of bits set 14553in a value. 14554 14555Arguments: 14556"""""""""" 14557 14558The only argument is the value to be counted. The argument may be of any 14559integer type, or a vector with integer elements. The return type must 14560match the argument type. 14561 14562Semantics: 14563"""""""""" 14564 14565The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within 14566each element of a vector. 14567 14568'``llvm.ctlz.*``' Intrinsic 14569^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14570 14571Syntax: 14572""""""" 14573 14574This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any 14575integer bit width, or any vector whose elements are integers. Not all 14576targets support all bit widths or vector types, however. 14577 14578:: 14579 14580 declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>) 14581 declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>) 14582 declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>) 14583 declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>) 14584 declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>) 14585 declare <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) 14586 14587Overview: 14588""""""""" 14589 14590The '``llvm.ctlz``' family of intrinsic functions counts the number of 14591leading zeros in a variable. 14592 14593Arguments: 14594"""""""""" 14595 14596The first argument is the value to be counted. This argument may be of 14597any integer type, or a vector with integer element type. The return 14598type must match the first argument type. 14599 14600The second argument must be a constant and is a flag to indicate whether 14601the intrinsic should ensure that a zero as the first argument produces a 14602defined result. Historically some architectures did not provide a 14603defined result for zero values as efficiently, and many algorithms are 14604now predicated on avoiding zero-value inputs. 14605 14606Semantics: 14607"""""""""" 14608 14609The '``llvm.ctlz``' intrinsic counts the leading (most significant) 14610zeros in a variable, or within each element of the vector. If 14611``src == 0`` then the result is the size in bits of the type of ``src`` 14612if ``is_zero_undef == 0`` and ``undef`` otherwise. For example, 14613``llvm.ctlz(i32 2) = 30``. 14614 14615'``llvm.cttz.*``' Intrinsic 14616^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14617 14618Syntax: 14619""""""" 14620 14621This is an overloaded intrinsic. You can use ``llvm.cttz`` on any 14622integer bit width, or any vector of integer elements. Not all targets 14623support all bit widths or vector types, however. 14624 14625:: 14626 14627 declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>) 14628 declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>) 14629 declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>) 14630 declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>) 14631 declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>) 14632 declare <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) 14633 14634Overview: 14635""""""""" 14636 14637The '``llvm.cttz``' family of intrinsic functions counts the number of 14638trailing zeros. 14639 14640Arguments: 14641"""""""""" 14642 14643The first argument is the value to be counted. This argument may be of 14644any integer type, or a vector with integer element type. The return 14645type must match the first argument type. 14646 14647The second argument must be a constant and is a flag to indicate whether 14648the intrinsic should ensure that a zero as the first argument produces a 14649defined result. Historically some architectures did not provide a 14650defined result for zero values as efficiently, and many algorithms are 14651now predicated on avoiding zero-value inputs. 14652 14653Semantics: 14654"""""""""" 14655 14656The '``llvm.cttz``' intrinsic counts the trailing (least significant) 14657zeros in a variable, or within each element of a vector. If ``src == 0`` 14658then the result is the size in bits of the type of ``src`` if 14659``is_zero_undef == 0`` and ``undef`` otherwise. For example, 14660``llvm.cttz(2) = 1``. 14661 14662.. _int_overflow: 14663 14664'``llvm.fshl.*``' Intrinsic 14665^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14666 14667Syntax: 14668""""""" 14669 14670This is an overloaded intrinsic. You can use ``llvm.fshl`` on any 14671integer bit width or any vector of integer elements. Not all targets 14672support all bit widths or vector types, however. 14673 14674:: 14675 14676 declare i8 @llvm.fshl.i8 (i8 %a, i8 %b, i8 %c) 14677 declare i67 @llvm.fshl.i67(i67 %a, i67 %b, i67 %c) 14678 declare <2 x i32> @llvm.fshl.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c) 14679 14680Overview: 14681""""""""" 14682 14683The '``llvm.fshl``' family of intrinsic functions performs a funnel shift left: 14684the first two values are concatenated as { %a : %b } (%a is the most significant 14685bits of the wide value), the combined value is shifted left, and the most 14686significant bits are extracted to produce a result that is the same size as the 14687original arguments. If the first 2 arguments are identical, this is equivalent 14688to a rotate left operation. For vector types, the operation occurs for each 14689element of the vector. The shift argument is treated as an unsigned amount 14690modulo the element size of the arguments. 14691 14692Arguments: 14693"""""""""" 14694 14695The first two arguments are the values to be concatenated. The third 14696argument is the shift amount. The arguments may be any integer type or a 14697vector with integer element type. All arguments and the return value must 14698have the same type. 14699 14700Example: 14701"""""""" 14702 14703.. code-block:: text 14704 14705 %r = call i8 @llvm.fshl.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: msb_extract((concat(x, y) << (z % 8)), 8) 14706 %r = call i8 @llvm.fshl.i8(i8 255, i8 0, i8 15) ; %r = i8: 128 (0b10000000) 14707 %r = call i8 @llvm.fshl.i8(i8 15, i8 15, i8 11) ; %r = i8: 120 (0b01111000) 14708 %r = call i8 @llvm.fshl.i8(i8 0, i8 255, i8 8) ; %r = i8: 0 (0b00000000) 14709 14710'``llvm.fshr.*``' Intrinsic 14711^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14712 14713Syntax: 14714""""""" 14715 14716This is an overloaded intrinsic. You can use ``llvm.fshr`` on any 14717integer bit width or any vector of integer elements. Not all targets 14718support all bit widths or vector types, however. 14719 14720:: 14721 14722 declare i8 @llvm.fshr.i8 (i8 %a, i8 %b, i8 %c) 14723 declare i67 @llvm.fshr.i67(i67 %a, i67 %b, i67 %c) 14724 declare <2 x i32> @llvm.fshr.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c) 14725 14726Overview: 14727""""""""" 14728 14729The '``llvm.fshr``' family of intrinsic functions performs a funnel shift right: 14730the first two values are concatenated as { %a : %b } (%a is the most significant 14731bits of the wide value), the combined value is shifted right, and the least 14732significant bits are extracted to produce a result that is the same size as the 14733original arguments. If the first 2 arguments are identical, this is equivalent 14734to a rotate right operation. For vector types, the operation occurs for each 14735element of the vector. The shift argument is treated as an unsigned amount 14736modulo the element size of the arguments. 14737 14738Arguments: 14739"""""""""" 14740 14741The first two arguments are the values to be concatenated. The third 14742argument is the shift amount. The arguments may be any integer type or a 14743vector with integer element type. All arguments and the return value must 14744have the same type. 14745 14746Example: 14747"""""""" 14748 14749.. code-block:: text 14750 14751 %r = call i8 @llvm.fshr.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: lsb_extract((concat(x, y) >> (z % 8)), 8) 14752 %r = call i8 @llvm.fshr.i8(i8 255, i8 0, i8 15) ; %r = i8: 254 (0b11111110) 14753 %r = call i8 @llvm.fshr.i8(i8 15, i8 15, i8 11) ; %r = i8: 225 (0b11100001) 14754 %r = call i8 @llvm.fshr.i8(i8 0, i8 255, i8 8) ; %r = i8: 255 (0b11111111) 14755 14756Arithmetic with Overflow Intrinsics 14757----------------------------------- 14758 14759LLVM provides intrinsics for fast arithmetic overflow checking. 14760 14761Each of these intrinsics returns a two-element struct. The first 14762element of this struct contains the result of the corresponding 14763arithmetic operation modulo 2\ :sup:`n`\ , where n is the bit width of 14764the result. Therefore, for example, the first element of the struct 14765returned by ``llvm.sadd.with.overflow.i32`` is always the same as the 14766result of a 32-bit ``add`` instruction with the same operands, where 14767the ``add`` is *not* modified by an ``nsw`` or ``nuw`` flag. 14768 14769The second element of the result is an ``i1`` that is 1 if the 14770arithmetic operation overflowed and 0 otherwise. An operation 14771overflows if, for any values of its operands ``A`` and ``B`` and for 14772any ``N`` larger than the operands' width, ``ext(A op B) to iN`` is 14773not equal to ``(ext(A) to iN) op (ext(B) to iN)`` where ``ext`` is 14774``sext`` for signed overflow and ``zext`` for unsigned overflow, and 14775``op`` is the underlying arithmetic operation. 14776 14777The behavior of these intrinsics is well-defined for all argument 14778values. 14779 14780'``llvm.sadd.with.overflow.*``' Intrinsics 14781^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14782 14783Syntax: 14784""""""" 14785 14786This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow`` 14787on any integer bit width or vectors of integers. 14788 14789:: 14790 14791 declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) 14792 declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 14793 declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b) 14794 declare {<4 x i32>, <4 x i1>} @llvm.sadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 14795 14796Overview: 14797""""""""" 14798 14799The '``llvm.sadd.with.overflow``' family of intrinsic functions perform 14800a signed addition of the two arguments, and indicate whether an overflow 14801occurred during the signed summation. 14802 14803Arguments: 14804"""""""""" 14805 14806The arguments (%a and %b) and the first element of the result structure 14807may be of integer types of any bit width, but they must have the same 14808bit width. The second element of the result structure must be of type 14809``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 14810addition. 14811 14812Semantics: 14813"""""""""" 14814 14815The '``llvm.sadd.with.overflow``' family of intrinsic functions perform 14816a signed addition of the two variables. They return a structure --- the 14817first element of which is the signed summation, and the second element 14818of which is a bit specifying if the signed summation resulted in an 14819overflow. 14820 14821Examples: 14822""""""""" 14823 14824.. code-block:: llvm 14825 14826 %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 14827 %sum = extractvalue {i32, i1} %res, 0 14828 %obit = extractvalue {i32, i1} %res, 1 14829 br i1 %obit, label %overflow, label %normal 14830 14831'``llvm.uadd.with.overflow.*``' Intrinsics 14832^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14833 14834Syntax: 14835""""""" 14836 14837This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow`` 14838on any integer bit width or vectors of integers. 14839 14840:: 14841 14842 declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b) 14843 declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 14844 declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b) 14845 declare {<4 x i32>, <4 x i1>} @llvm.uadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 14846 14847Overview: 14848""""""""" 14849 14850The '``llvm.uadd.with.overflow``' family of intrinsic functions perform 14851an unsigned addition of the two arguments, and indicate whether a carry 14852occurred during the unsigned summation. 14853 14854Arguments: 14855"""""""""" 14856 14857The arguments (%a and %b) and the first element of the result structure 14858may be of integer types of any bit width, but they must have the same 14859bit width. The second element of the result structure must be of type 14860``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 14861addition. 14862 14863Semantics: 14864"""""""""" 14865 14866The '``llvm.uadd.with.overflow``' family of intrinsic functions perform 14867an unsigned addition of the two arguments. They return a structure --- the 14868first element of which is the sum, and the second element of which is a 14869bit specifying if the unsigned summation resulted in a carry. 14870 14871Examples: 14872""""""""" 14873 14874.. code-block:: llvm 14875 14876 %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 14877 %sum = extractvalue {i32, i1} %res, 0 14878 %obit = extractvalue {i32, i1} %res, 1 14879 br i1 %obit, label %carry, label %normal 14880 14881'``llvm.ssub.with.overflow.*``' Intrinsics 14882^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14883 14884Syntax: 14885""""""" 14886 14887This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow`` 14888on any integer bit width or vectors of integers. 14889 14890:: 14891 14892 declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b) 14893 declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 14894 declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b) 14895 declare {<4 x i32>, <4 x i1>} @llvm.ssub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 14896 14897Overview: 14898""""""""" 14899 14900The '``llvm.ssub.with.overflow``' family of intrinsic functions perform 14901a signed subtraction of the two arguments, and indicate whether an 14902overflow occurred during the signed subtraction. 14903 14904Arguments: 14905"""""""""" 14906 14907The arguments (%a and %b) and the first element of the result structure 14908may be of integer types of any bit width, but they must have the same 14909bit width. The second element of the result structure must be of type 14910``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 14911subtraction. 14912 14913Semantics: 14914"""""""""" 14915 14916The '``llvm.ssub.with.overflow``' family of intrinsic functions perform 14917a signed subtraction of the two arguments. They return a structure --- the 14918first element of which is the subtraction, and the second element of 14919which is a bit specifying if the signed subtraction resulted in an 14920overflow. 14921 14922Examples: 14923""""""""" 14924 14925.. code-block:: llvm 14926 14927 %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 14928 %sum = extractvalue {i32, i1} %res, 0 14929 %obit = extractvalue {i32, i1} %res, 1 14930 br i1 %obit, label %overflow, label %normal 14931 14932'``llvm.usub.with.overflow.*``' Intrinsics 14933^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14934 14935Syntax: 14936""""""" 14937 14938This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow`` 14939on any integer bit width or vectors of integers. 14940 14941:: 14942 14943 declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b) 14944 declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 14945 declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b) 14946 declare {<4 x i32>, <4 x i1>} @llvm.usub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 14947 14948Overview: 14949""""""""" 14950 14951The '``llvm.usub.with.overflow``' family of intrinsic functions perform 14952an unsigned subtraction of the two arguments, and indicate whether an 14953overflow occurred during the unsigned subtraction. 14954 14955Arguments: 14956"""""""""" 14957 14958The arguments (%a and %b) and the first element of the result structure 14959may be of integer types of any bit width, but they must have the same 14960bit width. The second element of the result structure must be of type 14961``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 14962subtraction. 14963 14964Semantics: 14965"""""""""" 14966 14967The '``llvm.usub.with.overflow``' family of intrinsic functions perform 14968an unsigned subtraction of the two arguments. They return a structure --- 14969the first element of which is the subtraction, and the second element of 14970which is a bit specifying if the unsigned subtraction resulted in an 14971overflow. 14972 14973Examples: 14974""""""""" 14975 14976.. code-block:: llvm 14977 14978 %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 14979 %sum = extractvalue {i32, i1} %res, 0 14980 %obit = extractvalue {i32, i1} %res, 1 14981 br i1 %obit, label %overflow, label %normal 14982 14983'``llvm.smul.with.overflow.*``' Intrinsics 14984^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14985 14986Syntax: 14987""""""" 14988 14989This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow`` 14990on any integer bit width or vectors of integers. 14991 14992:: 14993 14994 declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b) 14995 declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 14996 declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b) 14997 declare {<4 x i32>, <4 x i1>} @llvm.smul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 14998 14999Overview: 15000""""""""" 15001 15002The '``llvm.smul.with.overflow``' family of intrinsic functions perform 15003a signed multiplication of the two arguments, and indicate whether an 15004overflow occurred during the signed multiplication. 15005 15006Arguments: 15007"""""""""" 15008 15009The arguments (%a and %b) and the first element of the result structure 15010may be of integer types of any bit width, but they must have the same 15011bit width. The second element of the result structure must be of type 15012``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 15013multiplication. 15014 15015Semantics: 15016"""""""""" 15017 15018The '``llvm.smul.with.overflow``' family of intrinsic functions perform 15019a signed multiplication of the two arguments. They return a structure --- 15020the first element of which is the multiplication, and the second element 15021of which is a bit specifying if the signed multiplication resulted in an 15022overflow. 15023 15024Examples: 15025""""""""" 15026 15027.. code-block:: llvm 15028 15029 %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 15030 %sum = extractvalue {i32, i1} %res, 0 15031 %obit = extractvalue {i32, i1} %res, 1 15032 br i1 %obit, label %overflow, label %normal 15033 15034'``llvm.umul.with.overflow.*``' Intrinsics 15035^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15036 15037Syntax: 15038""""""" 15039 15040This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow`` 15041on any integer bit width or vectors of integers. 15042 15043:: 15044 15045 declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b) 15046 declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 15047 declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b) 15048 declare {<4 x i32>, <4 x i1>} @llvm.umul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 15049 15050Overview: 15051""""""""" 15052 15053The '``llvm.umul.with.overflow``' family of intrinsic functions perform 15054a unsigned multiplication of the two arguments, and indicate whether an 15055overflow occurred during the unsigned multiplication. 15056 15057Arguments: 15058"""""""""" 15059 15060The arguments (%a and %b) and the first element of the result structure 15061may be of integer types of any bit width, but they must have the same 15062bit width. The second element of the result structure must be of type 15063``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 15064multiplication. 15065 15066Semantics: 15067"""""""""" 15068 15069The '``llvm.umul.with.overflow``' family of intrinsic functions perform 15070an unsigned multiplication of the two arguments. They return a structure --- 15071the first element of which is the multiplication, and the second 15072element of which is a bit specifying if the unsigned multiplication 15073resulted in an overflow. 15074 15075Examples: 15076""""""""" 15077 15078.. code-block:: llvm 15079 15080 %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 15081 %sum = extractvalue {i32, i1} %res, 0 15082 %obit = extractvalue {i32, i1} %res, 1 15083 br i1 %obit, label %overflow, label %normal 15084 15085Saturation Arithmetic Intrinsics 15086--------------------------------- 15087 15088Saturation arithmetic is a version of arithmetic in which operations are 15089limited to a fixed range between a minimum and maximum value. If the result of 15090an operation is greater than the maximum value, the result is set (or 15091"clamped") to this maximum. If it is below the minimum, it is clamped to this 15092minimum. 15093 15094 15095'``llvm.sadd.sat.*``' Intrinsics 15096^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15097 15098Syntax 15099""""""" 15100 15101This is an overloaded intrinsic. You can use ``llvm.sadd.sat`` 15102on any integer bit width or vectors of integers. 15103 15104:: 15105 15106 declare i16 @llvm.sadd.sat.i16(i16 %a, i16 %b) 15107 declare i32 @llvm.sadd.sat.i32(i32 %a, i32 %b) 15108 declare i64 @llvm.sadd.sat.i64(i64 %a, i64 %b) 15109 declare <4 x i32> @llvm.sadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15110 15111Overview 15112""""""""" 15113 15114The '``llvm.sadd.sat``' family of intrinsic functions perform signed 15115saturating addition on the 2 arguments. 15116 15117Arguments 15118"""""""""" 15119 15120The arguments (%a and %b) and the result may be of integer types of any bit 15121width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15122values that will undergo signed addition. 15123 15124Semantics: 15125"""""""""" 15126 15127The maximum value this operation can clamp to is the largest signed value 15128representable by the bit width of the arguments. The minimum value is the 15129smallest signed value representable by this bit width. 15130 15131 15132Examples 15133""""""""" 15134 15135.. code-block:: llvm 15136 15137 %res = call i4 @llvm.sadd.sat.i4(i4 1, i4 2) ; %res = 3 15138 %res = call i4 @llvm.sadd.sat.i4(i4 5, i4 6) ; %res = 7 15139 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 2) ; %res = -2 15140 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 -5) ; %res = -8 15141 15142 15143'``llvm.uadd.sat.*``' Intrinsics 15144^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15145 15146Syntax 15147""""""" 15148 15149This is an overloaded intrinsic. You can use ``llvm.uadd.sat`` 15150on any integer bit width or vectors of integers. 15151 15152:: 15153 15154 declare i16 @llvm.uadd.sat.i16(i16 %a, i16 %b) 15155 declare i32 @llvm.uadd.sat.i32(i32 %a, i32 %b) 15156 declare i64 @llvm.uadd.sat.i64(i64 %a, i64 %b) 15157 declare <4 x i32> @llvm.uadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15158 15159Overview 15160""""""""" 15161 15162The '``llvm.uadd.sat``' family of intrinsic functions perform unsigned 15163saturating addition on the 2 arguments. 15164 15165Arguments 15166"""""""""" 15167 15168The arguments (%a and %b) and the result may be of integer types of any bit 15169width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15170values that will undergo unsigned addition. 15171 15172Semantics: 15173"""""""""" 15174 15175The maximum value this operation can clamp to is the largest unsigned value 15176representable by the bit width of the arguments. Because this is an unsigned 15177operation, the result will never saturate towards zero. 15178 15179 15180Examples 15181""""""""" 15182 15183.. code-block:: llvm 15184 15185 %res = call i4 @llvm.uadd.sat.i4(i4 1, i4 2) ; %res = 3 15186 %res = call i4 @llvm.uadd.sat.i4(i4 5, i4 6) ; %res = 11 15187 %res = call i4 @llvm.uadd.sat.i4(i4 8, i4 8) ; %res = 15 15188 15189 15190'``llvm.ssub.sat.*``' Intrinsics 15191^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15192 15193Syntax 15194""""""" 15195 15196This is an overloaded intrinsic. You can use ``llvm.ssub.sat`` 15197on any integer bit width or vectors of integers. 15198 15199:: 15200 15201 declare i16 @llvm.ssub.sat.i16(i16 %a, i16 %b) 15202 declare i32 @llvm.ssub.sat.i32(i32 %a, i32 %b) 15203 declare i64 @llvm.ssub.sat.i64(i64 %a, i64 %b) 15204 declare <4 x i32> @llvm.ssub.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15205 15206Overview 15207""""""""" 15208 15209The '``llvm.ssub.sat``' family of intrinsic functions perform signed 15210saturating subtraction on the 2 arguments. 15211 15212Arguments 15213"""""""""" 15214 15215The arguments (%a and %b) and the result may be of integer types of any bit 15216width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15217values that will undergo signed subtraction. 15218 15219Semantics: 15220"""""""""" 15221 15222The maximum value this operation can clamp to is the largest signed value 15223representable by the bit width of the arguments. The minimum value is the 15224smallest signed value representable by this bit width. 15225 15226 15227Examples 15228""""""""" 15229 15230.. code-block:: llvm 15231 15232 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 1) ; %res = 1 15233 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 6) ; %res = -4 15234 %res = call i4 @llvm.ssub.sat.i4(i4 -4, i4 5) ; %res = -8 15235 %res = call i4 @llvm.ssub.sat.i4(i4 4, i4 -5) ; %res = 7 15236 15237 15238'``llvm.usub.sat.*``' Intrinsics 15239^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15240 15241Syntax 15242""""""" 15243 15244This is an overloaded intrinsic. You can use ``llvm.usub.sat`` 15245on any integer bit width or vectors of integers. 15246 15247:: 15248 15249 declare i16 @llvm.usub.sat.i16(i16 %a, i16 %b) 15250 declare i32 @llvm.usub.sat.i32(i32 %a, i32 %b) 15251 declare i64 @llvm.usub.sat.i64(i64 %a, i64 %b) 15252 declare <4 x i32> @llvm.usub.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15253 15254Overview 15255""""""""" 15256 15257The '``llvm.usub.sat``' family of intrinsic functions perform unsigned 15258saturating subtraction on the 2 arguments. 15259 15260Arguments 15261"""""""""" 15262 15263The arguments (%a and %b) and the result may be of integer types of any bit 15264width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15265values that will undergo unsigned subtraction. 15266 15267Semantics: 15268"""""""""" 15269 15270The minimum value this operation can clamp to is 0, which is the smallest 15271unsigned value representable by the bit width of the unsigned arguments. 15272Because this is an unsigned operation, the result will never saturate towards 15273the largest possible value representable by this bit width. 15274 15275 15276Examples 15277""""""""" 15278 15279.. code-block:: llvm 15280 15281 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 1) ; %res = 1 15282 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 6) ; %res = 0 15283 15284 15285'``llvm.sshl.sat.*``' Intrinsics 15286^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15287 15288Syntax 15289""""""" 15290 15291This is an overloaded intrinsic. You can use ``llvm.sshl.sat`` 15292on integers or vectors of integers of any bit width. 15293 15294:: 15295 15296 declare i16 @llvm.sshl.sat.i16(i16 %a, i16 %b) 15297 declare i32 @llvm.sshl.sat.i32(i32 %a, i32 %b) 15298 declare i64 @llvm.sshl.sat.i64(i64 %a, i64 %b) 15299 declare <4 x i32> @llvm.sshl.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15300 15301Overview 15302""""""""" 15303 15304The '``llvm.sshl.sat``' family of intrinsic functions perform signed 15305saturating left shift on the first argument. 15306 15307Arguments 15308"""""""""" 15309 15310The arguments (``%a`` and ``%b``) and the result may be of integer types of any 15311bit width, but they must have the same bit width. ``%a`` is the value to be 15312shifted, and ``%b`` is the amount to shift by. If ``b`` is (statically or 15313dynamically) equal to or larger than the integer bit width of the arguments, 15314the result is a :ref:`poison value <poisonvalues>`. If the arguments are 15315vectors, each vector element of ``a`` is shifted by the corresponding shift 15316amount in ``b``. 15317 15318 15319Semantics: 15320"""""""""" 15321 15322The maximum value this operation can clamp to is the largest signed value 15323representable by the bit width of the arguments. The minimum value is the 15324smallest signed value representable by this bit width. 15325 15326 15327Examples 15328""""""""" 15329 15330.. code-block:: llvm 15331 15332 %res = call i4 @llvm.sshl.sat.i4(i4 2, i4 1) ; %res = 4 15333 %res = call i4 @llvm.sshl.sat.i4(i4 2, i4 2) ; %res = 7 15334 %res = call i4 @llvm.sshl.sat.i4(i4 -5, i4 1) ; %res = -8 15335 %res = call i4 @llvm.sshl.sat.i4(i4 -1, i4 1) ; %res = -2 15336 15337 15338'``llvm.ushl.sat.*``' Intrinsics 15339^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15340 15341Syntax 15342""""""" 15343 15344This is an overloaded intrinsic. You can use ``llvm.ushl.sat`` 15345on integers or vectors of integers of any bit width. 15346 15347:: 15348 15349 declare i16 @llvm.ushl.sat.i16(i16 %a, i16 %b) 15350 declare i32 @llvm.ushl.sat.i32(i32 %a, i32 %b) 15351 declare i64 @llvm.ushl.sat.i64(i64 %a, i64 %b) 15352 declare <4 x i32> @llvm.ushl.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15353 15354Overview 15355""""""""" 15356 15357The '``llvm.ushl.sat``' family of intrinsic functions perform unsigned 15358saturating left shift on the first argument. 15359 15360Arguments 15361"""""""""" 15362 15363The arguments (``%a`` and ``%b``) and the result may be of integer types of any 15364bit width, but they must have the same bit width. ``%a`` is the value to be 15365shifted, and ``%b`` is the amount to shift by. If ``b`` is (statically or 15366dynamically) equal to or larger than the integer bit width of the arguments, 15367the result is a :ref:`poison value <poisonvalues>`. If the arguments are 15368vectors, each vector element of ``a`` is shifted by the corresponding shift 15369amount in ``b``. 15370 15371Semantics: 15372"""""""""" 15373 15374The maximum value this operation can clamp to is the largest unsigned value 15375representable by the bit width of the arguments. 15376 15377 15378Examples 15379""""""""" 15380 15381.. code-block:: llvm 15382 15383 %res = call i4 @llvm.ushl.sat.i4(i4 2, i4 1) ; %res = 4 15384 %res = call i4 @llvm.ushl.sat.i4(i4 3, i4 3) ; %res = 15 15385 15386 15387Fixed Point Arithmetic Intrinsics 15388--------------------------------- 15389 15390A fixed point number represents a real data type for a number that has a fixed 15391number of digits after a radix point (equivalent to the decimal point '.'). 15392The number of digits after the radix point is referred as the `scale`. These 15393are useful for representing fractional values to a specific precision. The 15394following intrinsics perform fixed point arithmetic operations on 2 operands 15395of the same scale, specified as the third argument. 15396 15397The ``llvm.*mul.fix`` family of intrinsic functions represents a multiplication 15398of fixed point numbers through scaled integers. Therefore, fixed point 15399multiplication can be represented as 15400 15401.. code-block:: llvm 15402 15403 %result = call i4 @llvm.smul.fix.i4(i4 %a, i4 %b, i32 %scale) 15404 15405 ; Expands to 15406 %a2 = sext i4 %a to i8 15407 %b2 = sext i4 %b to i8 15408 %mul = mul nsw nuw i8 %a, %b 15409 %scale2 = trunc i32 %scale to i8 15410 %r = ashr i8 %mul, i8 %scale2 ; this is for a target rounding down towards negative infinity 15411 %result = trunc i8 %r to i4 15412 15413The ``llvm.*div.fix`` family of intrinsic functions represents a division of 15414fixed point numbers through scaled integers. Fixed point division can be 15415represented as: 15416 15417.. code-block:: llvm 15418 15419 %result call i4 @llvm.sdiv.fix.i4(i4 %a, i4 %b, i32 %scale) 15420 15421 ; Expands to 15422 %a2 = sext i4 %a to i8 15423 %b2 = sext i4 %b to i8 15424 %scale2 = trunc i32 %scale to i8 15425 %a3 = shl i8 %a2, %scale2 15426 %r = sdiv i8 %a3, %b2 ; this is for a target rounding towards zero 15427 %result = trunc i8 %r to i4 15428 15429For each of these functions, if the result cannot be represented exactly with 15430the provided scale, the result is rounded. Rounding is unspecified since 15431preferred rounding may vary for different targets. Rounding is specified 15432through a target hook. Different pipelines should legalize or optimize this 15433using the rounding specified by this hook if it is provided. Operations like 15434constant folding, instruction combining, KnownBits, and ValueTracking should 15435also use this hook, if provided, and not assume the direction of rounding. A 15436rounded result must always be within one unit of precision from the true 15437result. That is, the error between the returned result and the true result must 15438be less than 1/2^(scale). 15439 15440 15441'``llvm.smul.fix.*``' Intrinsics 15442^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15443 15444Syntax 15445""""""" 15446 15447This is an overloaded intrinsic. You can use ``llvm.smul.fix`` 15448on any integer bit width or vectors of integers. 15449 15450:: 15451 15452 declare i16 @llvm.smul.fix.i16(i16 %a, i16 %b, i32 %scale) 15453 declare i32 @llvm.smul.fix.i32(i32 %a, i32 %b, i32 %scale) 15454 declare i64 @llvm.smul.fix.i64(i64 %a, i64 %b, i32 %scale) 15455 declare <4 x i32> @llvm.smul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15456 15457Overview 15458""""""""" 15459 15460The '``llvm.smul.fix``' family of intrinsic functions perform signed 15461fixed point multiplication on 2 arguments of the same scale. 15462 15463Arguments 15464"""""""""" 15465 15466The arguments (%a and %b) and the result may be of integer types of any bit 15467width, but they must have the same bit width. The arguments may also work with 15468int vectors of the same length and int size. ``%a`` and ``%b`` are the two 15469values that will undergo signed fixed point multiplication. The argument 15470``%scale`` represents the scale of both operands, and must be a constant 15471integer. 15472 15473Semantics: 15474"""""""""" 15475 15476This operation performs fixed point multiplication on the 2 arguments of a 15477specified scale. The result will also be returned in the same scale specified 15478in the third argument. 15479 15480If the result value cannot be precisely represented in the given scale, the 15481value is rounded up or down to the closest representable value. The rounding 15482direction is unspecified. 15483 15484It is undefined behavior if the result value does not fit within the range of 15485the fixed point type. 15486 15487 15488Examples 15489""""""""" 15490 15491.. code-block:: llvm 15492 15493 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 15494 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 15495 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 x -1 = -1.5) 15496 15497 ; The result in the following could be rounded up to -2 or down to -2.5 15498 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -3, i32 1) ; %res = -5 (or -4) (1.5 x -1.5 = -2.25) 15499 15500 15501'``llvm.umul.fix.*``' Intrinsics 15502^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15503 15504Syntax 15505""""""" 15506 15507This is an overloaded intrinsic. You can use ``llvm.umul.fix`` 15508on any integer bit width or vectors of integers. 15509 15510:: 15511 15512 declare i16 @llvm.umul.fix.i16(i16 %a, i16 %b, i32 %scale) 15513 declare i32 @llvm.umul.fix.i32(i32 %a, i32 %b, i32 %scale) 15514 declare i64 @llvm.umul.fix.i64(i64 %a, i64 %b, i32 %scale) 15515 declare <4 x i32> @llvm.umul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15516 15517Overview 15518""""""""" 15519 15520The '``llvm.umul.fix``' family of intrinsic functions perform unsigned 15521fixed point multiplication on 2 arguments of the same scale. 15522 15523Arguments 15524"""""""""" 15525 15526The arguments (%a and %b) and the result may be of integer types of any bit 15527width, but they must have the same bit width. The arguments may also work with 15528int vectors of the same length and int size. ``%a`` and ``%b`` are the two 15529values that will undergo unsigned fixed point multiplication. The argument 15530``%scale`` represents the scale of both operands, and must be a constant 15531integer. 15532 15533Semantics: 15534"""""""""" 15535 15536This operation performs unsigned fixed point multiplication on the 2 arguments of a 15537specified scale. The result will also be returned in the same scale specified 15538in the third argument. 15539 15540If the result value cannot be precisely represented in the given scale, the 15541value is rounded up or down to the closest representable value. The rounding 15542direction is unspecified. 15543 15544It is undefined behavior if the result value does not fit within the range of 15545the fixed point type. 15546 15547 15548Examples 15549""""""""" 15550 15551.. code-block:: llvm 15552 15553 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 15554 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 15555 15556 ; The result in the following could be rounded down to 3.5 or up to 4 15557 %res = call i4 @llvm.umul.fix.i4(i4 15, i4 1, i32 1) ; %res = 7 (or 8) (7.5 x 0.5 = 3.75) 15558 15559 15560'``llvm.smul.fix.sat.*``' Intrinsics 15561^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15562 15563Syntax 15564""""""" 15565 15566This is an overloaded intrinsic. You can use ``llvm.smul.fix.sat`` 15567on any integer bit width or vectors of integers. 15568 15569:: 15570 15571 declare i16 @llvm.smul.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 15572 declare i32 @llvm.smul.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 15573 declare i64 @llvm.smul.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 15574 declare <4 x i32> @llvm.smul.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15575 15576Overview 15577""""""""" 15578 15579The '``llvm.smul.fix.sat``' family of intrinsic functions perform signed 15580fixed point saturating multiplication on 2 arguments of the same scale. 15581 15582Arguments 15583"""""""""" 15584 15585The arguments (%a and %b) and the result may be of integer types of any bit 15586width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15587values that will undergo signed fixed point multiplication. The argument 15588``%scale`` represents the scale of both operands, and must be a constant 15589integer. 15590 15591Semantics: 15592"""""""""" 15593 15594This operation performs fixed point multiplication on the 2 arguments of a 15595specified scale. The result will also be returned in the same scale specified 15596in the third argument. 15597 15598If the result value cannot be precisely represented in the given scale, the 15599value is rounded up or down to the closest representable value. The rounding 15600direction is unspecified. 15601 15602The maximum value this operation can clamp to is the largest signed value 15603representable by the bit width of the first 2 arguments. The minimum value is the 15604smallest signed value representable by this bit width. 15605 15606 15607Examples 15608""""""""" 15609 15610.. code-block:: llvm 15611 15612 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 15613 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 15614 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 x -1 = -1.5) 15615 15616 ; The result in the following could be rounded up to -2 or down to -2.5 15617 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 -3, i32 1) ; %res = -5 (or -4) (1.5 x -1.5 = -2.25) 15618 15619 ; Saturation 15620 %res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 2, i32 0) ; %res = 7 15621 %res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 4, i32 2) ; %res = 7 15622 %res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 5, i32 2) ; %res = -8 15623 %res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 -2, i32 1) ; %res = 7 15624 15625 ; Scale can affect the saturation result 15626 %res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 0) ; %res = 7 (2 x 4 -> clamped to 7) 15627 %res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 1) ; %res = 4 (1 x 2 = 2) 15628 15629 15630'``llvm.umul.fix.sat.*``' Intrinsics 15631^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15632 15633Syntax 15634""""""" 15635 15636This is an overloaded intrinsic. You can use ``llvm.umul.fix.sat`` 15637on any integer bit width or vectors of integers. 15638 15639:: 15640 15641 declare i16 @llvm.umul.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 15642 declare i32 @llvm.umul.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 15643 declare i64 @llvm.umul.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 15644 declare <4 x i32> @llvm.umul.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15645 15646Overview 15647""""""""" 15648 15649The '``llvm.umul.fix.sat``' family of intrinsic functions perform unsigned 15650fixed point saturating multiplication on 2 arguments of the same scale. 15651 15652Arguments 15653"""""""""" 15654 15655The arguments (%a and %b) and the result may be of integer types of any bit 15656width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15657values that will undergo unsigned fixed point multiplication. The argument 15658``%scale`` represents the scale of both operands, and must be a constant 15659integer. 15660 15661Semantics: 15662"""""""""" 15663 15664This operation performs fixed point multiplication on the 2 arguments of a 15665specified scale. The result will also be returned in the same scale specified 15666in the third argument. 15667 15668If the result value cannot be precisely represented in the given scale, the 15669value is rounded up or down to the closest representable value. The rounding 15670direction is unspecified. 15671 15672The maximum value this operation can clamp to is the largest unsigned value 15673representable by the bit width of the first 2 arguments. The minimum value is the 15674smallest unsigned value representable by this bit width (zero). 15675 15676 15677Examples 15678""""""""" 15679 15680.. code-block:: llvm 15681 15682 %res = call i4 @llvm.umul.fix.sat.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 15683 %res = call i4 @llvm.umul.fix.sat.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 15684 15685 ; The result in the following could be rounded down to 2 or up to 2.5 15686 %res = call i4 @llvm.umul.fix.sat.i4(i4 3, i4 3, i32 1) ; %res = 4 (or 5) (1.5 x 1.5 = 2.25) 15687 15688 ; Saturation 15689 %res = call i4 @llvm.umul.fix.sat.i4(i4 8, i4 2, i32 0) ; %res = 15 (8 x 2 -> clamped to 15) 15690 %res = call i4 @llvm.umul.fix.sat.i4(i4 8, i4 8, i32 2) ; %res = 15 (2 x 2 -> clamped to 3.75) 15691 15692 ; Scale can affect the saturation result 15693 %res = call i4 @llvm.umul.fix.sat.i4(i4 2, i4 4, i32 0) ; %res = 7 (2 x 4 -> clamped to 7) 15694 %res = call i4 @llvm.umul.fix.sat.i4(i4 2, i4 4, i32 1) ; %res = 4 (1 x 2 = 2) 15695 15696 15697'``llvm.sdiv.fix.*``' Intrinsics 15698^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15699 15700Syntax 15701""""""" 15702 15703This is an overloaded intrinsic. You can use ``llvm.sdiv.fix`` 15704on any integer bit width or vectors of integers. 15705 15706:: 15707 15708 declare i16 @llvm.sdiv.fix.i16(i16 %a, i16 %b, i32 %scale) 15709 declare i32 @llvm.sdiv.fix.i32(i32 %a, i32 %b, i32 %scale) 15710 declare i64 @llvm.sdiv.fix.i64(i64 %a, i64 %b, i32 %scale) 15711 declare <4 x i32> @llvm.sdiv.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15712 15713Overview 15714""""""""" 15715 15716The '``llvm.sdiv.fix``' family of intrinsic functions perform signed 15717fixed point division on 2 arguments of the same scale. 15718 15719Arguments 15720"""""""""" 15721 15722The arguments (%a and %b) and the result may be of integer types of any bit 15723width, but they must have the same bit width. The arguments may also work with 15724int vectors of the same length and int size. ``%a`` and ``%b`` are the two 15725values that will undergo signed fixed point division. The argument 15726``%scale`` represents the scale of both operands, and must be a constant 15727integer. 15728 15729Semantics: 15730"""""""""" 15731 15732This operation performs fixed point division on the 2 arguments of a 15733specified scale. The result will also be returned in the same scale specified 15734in the third argument. 15735 15736If the result value cannot be precisely represented in the given scale, the 15737value is rounded up or down to the closest representable value. The rounding 15738direction is unspecified. 15739 15740It is undefined behavior if the result value does not fit within the range of 15741the fixed point type, or if the second argument is zero. 15742 15743 15744Examples 15745""""""""" 15746 15747.. code-block:: llvm 15748 15749 %res = call i4 @llvm.sdiv.fix.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 15750 %res = call i4 @llvm.sdiv.fix.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 15751 %res = call i4 @llvm.sdiv.fix.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 / -1 = -1.5) 15752 15753 ; The result in the following could be rounded up to 1 or down to 0.5 15754 %res = call i4 @llvm.sdiv.fix.i4(i4 3, i4 4, i32 1) ; %res = 2 (or 1) (1.5 / 2 = 0.75) 15755 15756 15757'``llvm.udiv.fix.*``' Intrinsics 15758^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15759 15760Syntax 15761""""""" 15762 15763This is an overloaded intrinsic. You can use ``llvm.udiv.fix`` 15764on any integer bit width or vectors of integers. 15765 15766:: 15767 15768 declare i16 @llvm.udiv.fix.i16(i16 %a, i16 %b, i32 %scale) 15769 declare i32 @llvm.udiv.fix.i32(i32 %a, i32 %b, i32 %scale) 15770 declare i64 @llvm.udiv.fix.i64(i64 %a, i64 %b, i32 %scale) 15771 declare <4 x i32> @llvm.udiv.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15772 15773Overview 15774""""""""" 15775 15776The '``llvm.udiv.fix``' family of intrinsic functions perform unsigned 15777fixed point division on 2 arguments of the same scale. 15778 15779Arguments 15780"""""""""" 15781 15782The arguments (%a and %b) and the result may be of integer types of any bit 15783width, but they must have the same bit width. The arguments may also work with 15784int vectors of the same length and int size. ``%a`` and ``%b`` are the two 15785values that will undergo unsigned fixed point division. The argument 15786``%scale`` represents the scale of both operands, and must be a constant 15787integer. 15788 15789Semantics: 15790"""""""""" 15791 15792This operation performs fixed point division on the 2 arguments of a 15793specified scale. The result will also be returned in the same scale specified 15794in the third argument. 15795 15796If the result value cannot be precisely represented in the given scale, the 15797value is rounded up or down to the closest representable value. The rounding 15798direction is unspecified. 15799 15800It is undefined behavior if the result value does not fit within the range of 15801the fixed point type, or if the second argument is zero. 15802 15803 15804Examples 15805""""""""" 15806 15807.. code-block:: llvm 15808 15809 %res = call i4 @llvm.udiv.fix.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 15810 %res = call i4 @llvm.udiv.fix.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 15811 %res = call i4 @llvm.udiv.fix.i4(i4 1, i4 -8, i32 4) ; %res = 2 (0.0625 / 0.5 = 0.125) 15812 15813 ; The result in the following could be rounded up to 1 or down to 0.5 15814 %res = call i4 @llvm.udiv.fix.i4(i4 3, i4 4, i32 1) ; %res = 2 (or 1) (1.5 / 2 = 0.75) 15815 15816 15817'``llvm.sdiv.fix.sat.*``' Intrinsics 15818^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15819 15820Syntax 15821""""""" 15822 15823This is an overloaded intrinsic. You can use ``llvm.sdiv.fix.sat`` 15824on any integer bit width or vectors of integers. 15825 15826:: 15827 15828 declare i16 @llvm.sdiv.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 15829 declare i32 @llvm.sdiv.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 15830 declare i64 @llvm.sdiv.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 15831 declare <4 x i32> @llvm.sdiv.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15832 15833Overview 15834""""""""" 15835 15836The '``llvm.sdiv.fix.sat``' family of intrinsic functions perform signed 15837fixed point saturating division on 2 arguments of the same scale. 15838 15839Arguments 15840"""""""""" 15841 15842The arguments (%a and %b) and the result may be of integer types of any bit 15843width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15844values that will undergo signed fixed point division. The argument 15845``%scale`` represents the scale of both operands, and must be a constant 15846integer. 15847 15848Semantics: 15849"""""""""" 15850 15851This operation performs fixed point division on the 2 arguments of a 15852specified scale. The result will also be returned in the same scale specified 15853in the third argument. 15854 15855If the result value cannot be precisely represented in the given scale, the 15856value is rounded up or down to the closest representable value. The rounding 15857direction is unspecified. 15858 15859The maximum value this operation can clamp to is the largest signed value 15860representable by the bit width of the first 2 arguments. The minimum value is the 15861smallest signed value representable by this bit width. 15862 15863It is undefined behavior if the second argument is zero. 15864 15865 15866Examples 15867""""""""" 15868 15869.. code-block:: llvm 15870 15871 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 15872 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 15873 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 / -1 = -1.5) 15874 15875 ; The result in the following could be rounded up to 1 or down to 0.5 15876 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 3, i4 4, i32 1) ; %res = 2 (or 1) (1.5 / 2 = 0.75) 15877 15878 ; Saturation 15879 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 -8, i4 -1, i32 0) ; %res = 7 (-8 / -1 = 8 => 7) 15880 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 4, i4 2, i32 2) ; %res = 7 (1 / 0.5 = 2 => 1.75) 15881 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 -4, i4 1, i32 2) ; %res = -8 (-1 / 0.25 = -4 => -2) 15882 15883 15884'``llvm.udiv.fix.sat.*``' Intrinsics 15885^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15886 15887Syntax 15888""""""" 15889 15890This is an overloaded intrinsic. You can use ``llvm.udiv.fix.sat`` 15891on any integer bit width or vectors of integers. 15892 15893:: 15894 15895 declare i16 @llvm.udiv.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 15896 declare i32 @llvm.udiv.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 15897 declare i64 @llvm.udiv.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 15898 declare <4 x i32> @llvm.udiv.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 15899 15900Overview 15901""""""""" 15902 15903The '``llvm.udiv.fix.sat``' family of intrinsic functions perform unsigned 15904fixed point saturating division on 2 arguments of the same scale. 15905 15906Arguments 15907"""""""""" 15908 15909The arguments (%a and %b) and the result may be of integer types of any bit 15910width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15911values that will undergo unsigned fixed point division. The argument 15912``%scale`` represents the scale of both operands, and must be a constant 15913integer. 15914 15915Semantics: 15916"""""""""" 15917 15918This operation performs fixed point division on the 2 arguments of a 15919specified scale. The result will also be returned in the same scale specified 15920in the third argument. 15921 15922If the result value cannot be precisely represented in the given scale, the 15923value is rounded up or down to the closest representable value. The rounding 15924direction is unspecified. 15925 15926The maximum value this operation can clamp to is the largest unsigned value 15927representable by the bit width of the first 2 arguments. The minimum value is the 15928smallest unsigned value representable by this bit width (zero). 15929 15930It is undefined behavior if the second argument is zero. 15931 15932Examples 15933""""""""" 15934 15935.. code-block:: llvm 15936 15937 %res = call i4 @llvm.udiv.fix.sat.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 15938 %res = call i4 @llvm.udiv.fix.sat.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 15939 15940 ; The result in the following could be rounded down to 0.5 or up to 1 15941 %res = call i4 @llvm.udiv.fix.sat.i4(i4 3, i4 4, i32 1) ; %res = 1 (or 2) (1.5 / 2 = 0.75) 15942 15943 ; Saturation 15944 %res = call i4 @llvm.udiv.fix.sat.i4(i4 8, i4 2, i32 2) ; %res = 15 (2 / 0.5 = 4 => 3.75) 15945 15946 15947Specialised Arithmetic Intrinsics 15948--------------------------------- 15949 15950.. _i_intr_llvm_canonicalize: 15951 15952'``llvm.canonicalize.*``' Intrinsic 15953^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15954 15955Syntax: 15956""""""" 15957 15958:: 15959 15960 declare float @llvm.canonicalize.f32(float %a) 15961 declare double @llvm.canonicalize.f64(double %b) 15962 15963Overview: 15964""""""""" 15965 15966The '``llvm.canonicalize.*``' intrinsic returns the platform specific canonical 15967encoding of a floating-point number. This canonicalization is useful for 15968implementing certain numeric primitives such as frexp. The canonical encoding is 15969defined by IEEE-754-2008 to be: 15970 15971:: 15972 15973 2.1.8 canonical encoding: The preferred encoding of a floating-point 15974 representation in a format. Applied to declets, significands of finite 15975 numbers, infinities, and NaNs, especially in decimal formats. 15976 15977This operation can also be considered equivalent to the IEEE-754-2008 15978conversion of a floating-point value to the same format. NaNs are handled 15979according to section 6.2. 15980 15981Examples of non-canonical encodings: 15982 15983- x87 pseudo denormals, pseudo NaNs, pseudo Infinity, Unnormals. These are 15984 converted to a canonical representation per hardware-specific protocol. 15985- Many normal decimal floating-point numbers have non-canonical alternative 15986 encodings. 15987- Some machines, like GPUs or ARMv7 NEON, do not support subnormal values. 15988 These are treated as non-canonical encodings of zero and will be flushed to 15989 a zero of the same sign by this operation. 15990 15991Note that per IEEE-754-2008 6.2, systems that support signaling NaNs with 15992default exception handling must signal an invalid exception, and produce a 15993quiet NaN result. 15994 15995This function should always be implementable as multiplication by 1.0, provided 15996that the compiler does not constant fold the operation. Likewise, division by 159971.0 and ``llvm.minnum(x, x)`` are possible implementations. Addition with 15998-0.0 is also sufficient provided that the rounding mode is not -Infinity. 15999 16000``@llvm.canonicalize`` must preserve the equality relation. That is: 16001 16002- ``(@llvm.canonicalize(x) == x)`` is equivalent to ``(x == x)`` 16003- ``(@llvm.canonicalize(x) == @llvm.canonicalize(y))`` is equivalent to 16004 to ``(x == y)`` 16005 16006Additionally, the sign of zero must be conserved: 16007``@llvm.canonicalize(-0.0) = -0.0`` and ``@llvm.canonicalize(+0.0) = +0.0`` 16008 16009The payload bits of a NaN must be conserved, with two exceptions. 16010First, environments which use only a single canonical representation of NaN 16011must perform said canonicalization. Second, SNaNs must be quieted per the 16012usual methods. 16013 16014The canonicalization operation may be optimized away if: 16015 16016- The input is known to be canonical. For example, it was produced by a 16017 floating-point operation that is required by the standard to be canonical. 16018- The result is consumed only by (or fused with) other floating-point 16019 operations. That is, the bits of the floating-point value are not examined. 16020 16021'``llvm.fmuladd.*``' Intrinsic 16022^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16023 16024Syntax: 16025""""""" 16026 16027:: 16028 16029 declare float @llvm.fmuladd.f32(float %a, float %b, float %c) 16030 declare double @llvm.fmuladd.f64(double %a, double %b, double %c) 16031 16032Overview: 16033""""""""" 16034 16035The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add 16036expressions that can be fused if the code generator determines that (a) the 16037target instruction set has support for a fused operation, and (b) that the 16038fused operation is more efficient than the equivalent, separate pair of mul 16039and add instructions. 16040 16041Arguments: 16042"""""""""" 16043 16044The '``llvm.fmuladd.*``' intrinsics each take three arguments: two 16045multiplicands, a and b, and an addend c. 16046 16047Semantics: 16048"""""""""" 16049 16050The expression: 16051 16052:: 16053 16054 %0 = call float @llvm.fmuladd.f32(%a, %b, %c) 16055 16056is equivalent to the expression a \* b + c, except that it is unspecified 16057whether rounding will be performed between the multiplication and addition 16058steps. Fusion is not guaranteed, even if the target platform supports it. 16059If a fused multiply-add is required, the corresponding 16060:ref:`llvm.fma <int_fma>` intrinsic function should be used instead. 16061This never sets errno, just as '``llvm.fma.*``'. 16062 16063Examples: 16064""""""""" 16065 16066.. code-block:: llvm 16067 16068 %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c 16069 16070 16071Hardware-Loop Intrinsics 16072------------------------ 16073 16074LLVM support several intrinsics to mark a loop as a hardware-loop. They are 16075hints to the backend which are required to lower these intrinsics further to target 16076specific instructions, or revert the hardware-loop to a normal loop if target 16077specific restriction are not met and a hardware-loop can't be generated. 16078 16079These intrinsics may be modified in the future and are not intended to be used 16080outside the backend. Thus, front-end and mid-level optimizations should not be 16081generating these intrinsics. 16082 16083 16084'``llvm.set.loop.iterations.*``' Intrinsic 16085^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16086 16087Syntax: 16088""""""" 16089 16090This is an overloaded intrinsic. 16091 16092:: 16093 16094 declare void @llvm.set.loop.iterations.i32(i32) 16095 declare void @llvm.set.loop.iterations.i64(i64) 16096 16097Overview: 16098""""""""" 16099 16100The '``llvm.set.loop.iterations.*``' intrinsics are used to specify the 16101hardware-loop trip count. They are placed in the loop preheader basic block and 16102are marked as ``IntrNoDuplicate`` to avoid optimizers duplicating these 16103instructions. 16104 16105Arguments: 16106"""""""""" 16107 16108The integer operand is the loop trip count of the hardware-loop, and thus 16109not e.g. the loop back-edge taken count. 16110 16111Semantics: 16112"""""""""" 16113 16114The '``llvm.set.loop.iterations.*``' intrinsics do not perform any arithmetic 16115on their operand. It's a hint to the backend that can use this to set up the 16116hardware-loop count with a target specific instruction, usually a move of this 16117value to a special register or a hardware-loop instruction. 16118 16119 16120'``llvm.start.loop.iterations.*``' Intrinsic 16121^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16122 16123Syntax: 16124""""""" 16125 16126This is an overloaded intrinsic. 16127 16128:: 16129 16130 declare i32 @llvm.start.loop.iterations.i32(i32) 16131 declare i64 @llvm.start.loop.iterations.i64(i64) 16132 16133Overview: 16134""""""""" 16135 16136The '``llvm.start.loop.iterations.*``' intrinsics are similar to the 16137'``llvm.set.loop.iterations.*``' intrinsics, used to specify the 16138hardware-loop trip count but also produce a value identical to the input 16139that can be used as the input to the loop. They are placed in the loop 16140preheader basic block and the output is expected to be the input to the 16141phi for the induction variable of the loop, decremented by the 16142'``llvm.loop.decrement.reg.*``'. 16143 16144Arguments: 16145"""""""""" 16146 16147The integer operand is the loop trip count of the hardware-loop, and thus 16148not e.g. the loop back-edge taken count. 16149 16150Semantics: 16151"""""""""" 16152 16153The '``llvm.start.loop.iterations.*``' intrinsics do not perform any arithmetic 16154on their operand. It's a hint to the backend that can use this to set up the 16155hardware-loop count with a target specific instruction, usually a move of this 16156value to a special register or a hardware-loop instruction. 16157 16158'``llvm.test.set.loop.iterations.*``' Intrinsic 16159^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16160 16161Syntax: 16162""""""" 16163 16164This is an overloaded intrinsic. 16165 16166:: 16167 16168 declare i1 @llvm.test.set.loop.iterations.i32(i32) 16169 declare i1 @llvm.test.set.loop.iterations.i64(i64) 16170 16171Overview: 16172""""""""" 16173 16174The '``llvm.test.set.loop.iterations.*``' intrinsics are used to specify the 16175the loop trip count, and also test that the given count is not zero, allowing 16176it to control entry to a while-loop. They are placed in the loop preheader's 16177predecessor basic block, and are marked as ``IntrNoDuplicate`` to avoid 16178optimizers duplicating these instructions. 16179 16180Arguments: 16181"""""""""" 16182 16183The integer operand is the loop trip count of the hardware-loop, and thus 16184not e.g. the loop back-edge taken count. 16185 16186Semantics: 16187"""""""""" 16188 16189The '``llvm.test.set.loop.iterations.*``' intrinsics do not perform any 16190arithmetic on their operand. It's a hint to the backend that can use this to 16191set up the hardware-loop count with a target specific instruction, usually a 16192move of this value to a special register or a hardware-loop instruction. 16193The result is the conditional value of whether the given count is not zero. 16194 16195 16196'``llvm.test.start.loop.iterations.*``' Intrinsic 16197^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16198 16199Syntax: 16200""""""" 16201 16202This is an overloaded intrinsic. 16203 16204:: 16205 16206 declare {i32, i1} @llvm.test.start.loop.iterations.i32(i32) 16207 declare {i64, i1} @llvm.test.start.loop.iterations.i64(i64) 16208 16209Overview: 16210""""""""" 16211 16212The '``llvm.test.start.loop.iterations.*``' intrinsics are similar to the 16213'``llvm.test.set.loop.iterations.*``' and '``llvm.start.loop.iterations.*``' 16214intrinsics, used to specify the hardware-loop trip count, but also produce a 16215value identical to the input that can be used as the input to the loop. The 16216second i1 output controls entry to a while-loop. 16217 16218Arguments: 16219"""""""""" 16220 16221The integer operand is the loop trip count of the hardware-loop, and thus 16222not e.g. the loop back-edge taken count. 16223 16224Semantics: 16225"""""""""" 16226 16227The '``llvm.test.start.loop.iterations.*``' intrinsics do not perform any 16228arithmetic on their operand. It's a hint to the backend that can use this to 16229set up the hardware-loop count with a target specific instruction, usually a 16230move of this value to a special register or a hardware-loop instruction. 16231The result is a pair of the input and a conditional value of whether the 16232given count is not zero. 16233 16234 16235'``llvm.loop.decrement.reg.*``' Intrinsic 16236^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16237 16238Syntax: 16239""""""" 16240 16241This is an overloaded intrinsic. 16242 16243:: 16244 16245 declare i32 @llvm.loop.decrement.reg.i32(i32, i32) 16246 declare i64 @llvm.loop.decrement.reg.i64(i64, i64) 16247 16248Overview: 16249""""""""" 16250 16251The '``llvm.loop.decrement.reg.*``' intrinsics are used to lower the loop 16252iteration counter and return an updated value that will be used in the next 16253loop test check. 16254 16255Arguments: 16256"""""""""" 16257 16258Both arguments must have identical integer types. The first operand is the 16259loop iteration counter. The second operand is the maximum number of elements 16260processed in an iteration. 16261 16262Semantics: 16263"""""""""" 16264 16265The '``llvm.loop.decrement.reg.*``' intrinsics do an integer ``SUB`` of its 16266two operands, which is not allowed to wrap. They return the remaining number of 16267iterations still to be executed, and can be used together with a ``PHI``, 16268``ICMP`` and ``BR`` to control the number of loop iterations executed. Any 16269optimisations are allowed to treat it is a ``SUB``, and it is supported by 16270SCEV, so it's the backends responsibility to handle cases where it may be 16271optimised. These intrinsics are marked as ``IntrNoDuplicate`` to avoid 16272optimizers duplicating these instructions. 16273 16274 16275'``llvm.loop.decrement.*``' Intrinsic 16276^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16277 16278Syntax: 16279""""""" 16280 16281This is an overloaded intrinsic. 16282 16283:: 16284 16285 declare i1 @llvm.loop.decrement.i32(i32) 16286 declare i1 @llvm.loop.decrement.i64(i64) 16287 16288Overview: 16289""""""""" 16290 16291The HardwareLoops pass allows the loop decrement value to be specified with an 16292option. It defaults to a loop decrement value of 1, but it can be an unsigned 16293integer value provided by this option. The '``llvm.loop.decrement.*``' 16294intrinsics decrement the loop iteration counter with this value, and return a 16295false predicate if the loop should exit, and true otherwise. 16296This is emitted if the loop counter is not updated via a ``PHI`` node, which 16297can also be controlled with an option. 16298 16299Arguments: 16300"""""""""" 16301 16302The integer argument is the loop decrement value used to decrement the loop 16303iteration counter. 16304 16305Semantics: 16306"""""""""" 16307 16308The '``llvm.loop.decrement.*``' intrinsics do a ``SUB`` of the loop iteration 16309counter with the given loop decrement value, and return false if the loop 16310should exit, this ``SUB`` is not allowed to wrap. The result is a condition 16311that is used by the conditional branch controlling the loop. 16312 16313 16314Vector Reduction Intrinsics 16315--------------------------- 16316 16317Horizontal reductions of vectors can be expressed using the following 16318intrinsics. Each one takes a vector operand as an input and applies its 16319respective operation across all elements of the vector, returning a single 16320scalar result of the same element type. 16321 16322 16323'``llvm.vector.reduce.add.*``' Intrinsic 16324^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16325 16326Syntax: 16327""""""" 16328 16329:: 16330 16331 declare i32 @llvm.vector.reduce.add.v4i32(<4 x i32> %a) 16332 declare i64 @llvm.vector.reduce.add.v2i64(<2 x i64> %a) 16333 16334Overview: 16335""""""""" 16336 16337The '``llvm.vector.reduce.add.*``' intrinsics do an integer ``ADD`` 16338reduction of a vector, returning the result as a scalar. The return type matches 16339the element-type of the vector input. 16340 16341Arguments: 16342"""""""""" 16343The argument to this intrinsic must be a vector of integer values. 16344 16345'``llvm.vector.reduce.fadd.*``' Intrinsic 16346^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16347 16348Syntax: 16349""""""" 16350 16351:: 16352 16353 declare float @llvm.vector.reduce.fadd.v4f32(float %start_value, <4 x float> %a) 16354 declare double @llvm.vector.reduce.fadd.v2f64(double %start_value, <2 x double> %a) 16355 16356Overview: 16357""""""""" 16358 16359The '``llvm.vector.reduce.fadd.*``' intrinsics do a floating-point 16360``ADD`` reduction of a vector, returning the result as a scalar. The return type 16361matches the element-type of the vector input. 16362 16363If the intrinsic call has the 'reassoc' flag set, then the reduction will not 16364preserve the associativity of an equivalent scalarized counterpart. Otherwise 16365the reduction will be *sequential*, thus implying that the operation respects 16366the associativity of a scalarized reduction. That is, the reduction begins with 16367the start value and performs an fadd operation with consecutively increasing 16368vector element indices. See the following pseudocode: 16369 16370:: 16371 16372 float sequential_fadd(start_value, input_vector) 16373 result = start_value 16374 for i = 0 to length(input_vector) 16375 result = result + input_vector[i] 16376 return result 16377 16378 16379Arguments: 16380"""""""""" 16381The first argument to this intrinsic is a scalar start value for the reduction. 16382The type of the start value matches the element-type of the vector input. 16383The second argument must be a vector of floating-point values. 16384 16385To ignore the start value, negative zero (``-0.0``) can be used, as it is 16386the neutral value of floating point addition. 16387 16388Examples: 16389""""""""" 16390 16391:: 16392 16393 %unord = call reassoc float @llvm.vector.reduce.fadd.v4f32(float -0.0, <4 x float> %input) ; relaxed reduction 16394 %ord = call float @llvm.vector.reduce.fadd.v4f32(float %start_value, <4 x float> %input) ; sequential reduction 16395 16396 16397'``llvm.vector.reduce.mul.*``' Intrinsic 16398^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16399 16400Syntax: 16401""""""" 16402 16403:: 16404 16405 declare i32 @llvm.vector.reduce.mul.v4i32(<4 x i32> %a) 16406 declare i64 @llvm.vector.reduce.mul.v2i64(<2 x i64> %a) 16407 16408Overview: 16409""""""""" 16410 16411The '``llvm.vector.reduce.mul.*``' intrinsics do an integer ``MUL`` 16412reduction of a vector, returning the result as a scalar. The return type matches 16413the element-type of the vector input. 16414 16415Arguments: 16416"""""""""" 16417The argument to this intrinsic must be a vector of integer values. 16418 16419'``llvm.vector.reduce.fmul.*``' Intrinsic 16420^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16421 16422Syntax: 16423""""""" 16424 16425:: 16426 16427 declare float @llvm.vector.reduce.fmul.v4f32(float %start_value, <4 x float> %a) 16428 declare double @llvm.vector.reduce.fmul.v2f64(double %start_value, <2 x double> %a) 16429 16430Overview: 16431""""""""" 16432 16433The '``llvm.vector.reduce.fmul.*``' intrinsics do a floating-point 16434``MUL`` reduction of a vector, returning the result as a scalar. The return type 16435matches the element-type of the vector input. 16436 16437If the intrinsic call has the 'reassoc' flag set, then the reduction will not 16438preserve the associativity of an equivalent scalarized counterpart. Otherwise 16439the reduction will be *sequential*, thus implying that the operation respects 16440the associativity of a scalarized reduction. That is, the reduction begins with 16441the start value and performs an fmul operation with consecutively increasing 16442vector element indices. See the following pseudocode: 16443 16444:: 16445 16446 float sequential_fmul(start_value, input_vector) 16447 result = start_value 16448 for i = 0 to length(input_vector) 16449 result = result * input_vector[i] 16450 return result 16451 16452 16453Arguments: 16454"""""""""" 16455The first argument to this intrinsic is a scalar start value for the reduction. 16456The type of the start value matches the element-type of the vector input. 16457The second argument must be a vector of floating-point values. 16458 16459To ignore the start value, one (``1.0``) can be used, as it is the neutral 16460value of floating point multiplication. 16461 16462Examples: 16463""""""""" 16464 16465:: 16466 16467 %unord = call reassoc float @llvm.vector.reduce.fmul.v4f32(float 1.0, <4 x float> %input) ; relaxed reduction 16468 %ord = call float @llvm.vector.reduce.fmul.v4f32(float %start_value, <4 x float> %input) ; sequential reduction 16469 16470'``llvm.vector.reduce.and.*``' Intrinsic 16471^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16472 16473Syntax: 16474""""""" 16475 16476:: 16477 16478 declare i32 @llvm.vector.reduce.and.v4i32(<4 x i32> %a) 16479 16480Overview: 16481""""""""" 16482 16483The '``llvm.vector.reduce.and.*``' intrinsics do a bitwise ``AND`` 16484reduction of a vector, returning the result as a scalar. The return type matches 16485the element-type of the vector input. 16486 16487Arguments: 16488"""""""""" 16489The argument to this intrinsic must be a vector of integer values. 16490 16491'``llvm.vector.reduce.or.*``' Intrinsic 16492^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16493 16494Syntax: 16495""""""" 16496 16497:: 16498 16499 declare i32 @llvm.vector.reduce.or.v4i32(<4 x i32> %a) 16500 16501Overview: 16502""""""""" 16503 16504The '``llvm.vector.reduce.or.*``' intrinsics do a bitwise ``OR`` reduction 16505of a vector, returning the result as a scalar. The return type matches the 16506element-type of the vector input. 16507 16508Arguments: 16509"""""""""" 16510The argument to this intrinsic must be a vector of integer values. 16511 16512'``llvm.vector.reduce.xor.*``' Intrinsic 16513^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16514 16515Syntax: 16516""""""" 16517 16518:: 16519 16520 declare i32 @llvm.vector.reduce.xor.v4i32(<4 x i32> %a) 16521 16522Overview: 16523""""""""" 16524 16525The '``llvm.vector.reduce.xor.*``' intrinsics do a bitwise ``XOR`` 16526reduction of a vector, returning the result as a scalar. The return type matches 16527the element-type of the vector input. 16528 16529Arguments: 16530"""""""""" 16531The argument to this intrinsic must be a vector of integer values. 16532 16533'``llvm.vector.reduce.smax.*``' Intrinsic 16534^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16535 16536Syntax: 16537""""""" 16538 16539:: 16540 16541 declare i32 @llvm.vector.reduce.smax.v4i32(<4 x i32> %a) 16542 16543Overview: 16544""""""""" 16545 16546The '``llvm.vector.reduce.smax.*``' intrinsics do a signed integer 16547``MAX`` reduction of a vector, returning the result as a scalar. The return type 16548matches the element-type of the vector input. 16549 16550Arguments: 16551"""""""""" 16552The argument to this intrinsic must be a vector of integer values. 16553 16554'``llvm.vector.reduce.smin.*``' Intrinsic 16555^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16556 16557Syntax: 16558""""""" 16559 16560:: 16561 16562 declare i32 @llvm.vector.reduce.smin.v4i32(<4 x i32> %a) 16563 16564Overview: 16565""""""""" 16566 16567The '``llvm.vector.reduce.smin.*``' intrinsics do a signed integer 16568``MIN`` reduction of a vector, returning the result as a scalar. The return type 16569matches the element-type of the vector input. 16570 16571Arguments: 16572"""""""""" 16573The argument to this intrinsic must be a vector of integer values. 16574 16575'``llvm.vector.reduce.umax.*``' Intrinsic 16576^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16577 16578Syntax: 16579""""""" 16580 16581:: 16582 16583 declare i32 @llvm.vector.reduce.umax.v4i32(<4 x i32> %a) 16584 16585Overview: 16586""""""""" 16587 16588The '``llvm.vector.reduce.umax.*``' intrinsics do an unsigned 16589integer ``MAX`` reduction of a vector, returning the result as a scalar. The 16590return type matches the element-type of the vector input. 16591 16592Arguments: 16593"""""""""" 16594The argument to this intrinsic must be a vector of integer values. 16595 16596'``llvm.vector.reduce.umin.*``' Intrinsic 16597^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16598 16599Syntax: 16600""""""" 16601 16602:: 16603 16604 declare i32 @llvm.vector.reduce.umin.v4i32(<4 x i32> %a) 16605 16606Overview: 16607""""""""" 16608 16609The '``llvm.vector.reduce.umin.*``' intrinsics do an unsigned 16610integer ``MIN`` reduction of a vector, returning the result as a scalar. The 16611return type matches the element-type of the vector input. 16612 16613Arguments: 16614"""""""""" 16615The argument to this intrinsic must be a vector of integer values. 16616 16617'``llvm.vector.reduce.fmax.*``' Intrinsic 16618^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16619 16620Syntax: 16621""""""" 16622 16623:: 16624 16625 declare float @llvm.vector.reduce.fmax.v4f32(<4 x float> %a) 16626 declare double @llvm.vector.reduce.fmax.v2f64(<2 x double> %a) 16627 16628Overview: 16629""""""""" 16630 16631The '``llvm.vector.reduce.fmax.*``' intrinsics do a floating-point 16632``MAX`` reduction of a vector, returning the result as a scalar. The return type 16633matches the element-type of the vector input. 16634 16635This instruction has the same comparison semantics as the '``llvm.maxnum.*``' 16636intrinsic. That is, the result will always be a number unless all elements of 16637the vector are NaN. For a vector with maximum element magnitude 0.0 and 16638containing both +0.0 and -0.0 elements, the sign of the result is unspecified. 16639 16640If the intrinsic call has the ``nnan`` fast-math flag, then the operation can 16641assume that NaNs are not present in the input vector. 16642 16643Arguments: 16644"""""""""" 16645The argument to this intrinsic must be a vector of floating-point values. 16646 16647'``llvm.vector.reduce.fmin.*``' Intrinsic 16648^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16649 16650Syntax: 16651""""""" 16652This is an overloaded intrinsic. 16653 16654:: 16655 16656 declare float @llvm.vector.reduce.fmin.v4f32(<4 x float> %a) 16657 declare double @llvm.vector.reduce.fmin.v2f64(<2 x double> %a) 16658 16659Overview: 16660""""""""" 16661 16662The '``llvm.vector.reduce.fmin.*``' intrinsics do a floating-point 16663``MIN`` reduction of a vector, returning the result as a scalar. The return type 16664matches the element-type of the vector input. 16665 16666This instruction has the same comparison semantics as the '``llvm.minnum.*``' 16667intrinsic. That is, the result will always be a number unless all elements of 16668the vector are NaN. For a vector with minimum element magnitude 0.0 and 16669containing both +0.0 and -0.0 elements, the sign of the result is unspecified. 16670 16671If the intrinsic call has the ``nnan`` fast-math flag, then the operation can 16672assume that NaNs are not present in the input vector. 16673 16674Arguments: 16675"""""""""" 16676The argument to this intrinsic must be a vector of floating-point values. 16677 16678'``llvm.experimental.vector.insert``' Intrinsic 16679^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16680 16681Syntax: 16682""""""" 16683This is an overloaded intrinsic. You can use ``llvm.experimental.vector.insert`` 16684to insert a fixed-width vector into a scalable vector, but not the other way 16685around. 16686 16687:: 16688 16689 declare <vscale x 4 x float> @llvm.experimental.vector.insert.v4f32(<vscale x 4 x float> %vec, <4 x float> %subvec, i64 %idx) 16690 declare <vscale x 2 x double> @llvm.experimental.vector.insert.v2f64(<vscale x 2 x double> %vec, <2 x double> %subvec, i64 %idx) 16691 16692Overview: 16693""""""""" 16694 16695The '``llvm.experimental.vector.insert.*``' intrinsics insert a vector into another vector 16696starting from a given index. The return type matches the type of the vector we 16697insert into. Conceptually, this can be used to build a scalable vector out of 16698non-scalable vectors. 16699 16700Arguments: 16701"""""""""" 16702 16703The ``vec`` is the vector which ``subvec`` will be inserted into. 16704The ``subvec`` is the vector that will be inserted. 16705 16706``idx`` represents the starting element number at which ``subvec`` will be 16707inserted. ``idx`` must be a constant multiple of ``subvec``'s known minimum 16708vector length. If ``subvec`` is a scalable vector, ``idx`` is first scaled by 16709the runtime scaling factor of ``subvec``. The elements of ``vec`` starting at 16710``idx`` are overwritten with ``subvec``. Elements ``idx`` through (``idx`` + 16711num_elements(``subvec``) - 1) must be valid ``vec`` indices. If this condition 16712cannot be determined statically but is false at runtime, then the result vector 16713is undefined. 16714 16715 16716'``llvm.experimental.vector.extract``' Intrinsic 16717^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16718 16719Syntax: 16720""""""" 16721This is an overloaded intrinsic. You can use 16722``llvm.experimental.vector.extract`` to extract a fixed-width vector from a 16723scalable vector, but not the other way around. 16724 16725:: 16726 16727 declare <4 x float> @llvm.experimental.vector.extract.v4f32(<vscale x 4 x float> %vec, i64 %idx) 16728 declare <2 x double> @llvm.experimental.vector.extract.v2f64(<vscale x 2 x double> %vec, i64 %idx) 16729 16730Overview: 16731""""""""" 16732 16733The '``llvm.experimental.vector.extract.*``' intrinsics extract a vector from 16734within another vector starting from a given index. The return type must be 16735explicitly specified. Conceptually, this can be used to decompose a scalable 16736vector into non-scalable parts. 16737 16738Arguments: 16739"""""""""" 16740 16741The ``vec`` is the vector from which we will extract a subvector. 16742 16743The ``idx`` specifies the starting element number within ``vec`` from which a 16744subvector is extracted. ``idx`` must be a constant multiple of the known-minimum 16745vector length of the result type. If the result type is a scalable vector, 16746``idx`` is first scaled by the result type's runtime scaling factor. Elements 16747``idx`` through (``idx`` + num_elements(result_type) - 1) must be valid vector 16748indices. If this condition cannot be determined statically but is false at 16749runtime, then the result vector is undefined. The ``idx`` parameter must be a 16750vector index constant type (for most targets this will be an integer pointer 16751type). 16752 16753'``llvm.experimental.vector.reverse``' Intrinsic 16754^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16755 16756Syntax: 16757""""""" 16758This is an overloaded intrinsic. 16759 16760:: 16761 16762 declare <2 x i8> @llvm.experimental.vector.reverse.v2i8(<2 x i8> %a) 16763 declare <vscale x 4 x i32> @llvm.experimental.vector.reverse.nxv4i32(<vscale x 4 x i32> %a) 16764 16765Overview: 16766""""""""" 16767 16768The '``llvm.experimental.vector.reverse.*``' intrinsics reverse a vector. 16769The intrinsic takes a single vector and returns a vector of matching type but 16770with the original lane order reversed. These intrinsics work for both fixed 16771and scalable vectors. While this intrinsic is marked as experimental the 16772recommended way to express reverse operations for fixed-width vectors is still 16773to use a shufflevector, as that may allow for more optimization opportunities. 16774 16775Arguments: 16776"""""""""" 16777 16778The argument to this intrinsic must be a vector. 16779 16780'``llvm.experimental.vector.splice``' Intrinsic 16781^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16782 16783Syntax: 16784""""""" 16785This is an overloaded intrinsic. 16786 16787:: 16788 16789 declare <2 x double> @llvm.experimental.vector.splice.v2f64(<2 x double> %vec1, <2 x double> %vec2, i32 %imm) 16790 declare <vscale x 4 x i32> @llvm.experimental.vector.splice.nxv4i32(<vscale x 4 x i32> %vec1, <vscale x 4 x i32> %vec2, i32 %imm) 16791 16792Overview: 16793""""""""" 16794 16795The '``llvm.experimental.vector.splice.*``' intrinsics construct a vector by 16796concatenating elements from the first input vector with elements of the second 16797input vector, returning a vector of the same type as the input vectors. The 16798signed immediate, modulo the number of elements in the vector, is the index 16799into the first vector from which to extract the result value. This means 16800conceptually that for a positive immediate, a vector is extracted from 16801``concat(%vec1, %vec2)`` starting at index ``imm``, whereas for a negative 16802immediate, it extracts ``-imm`` trailing elements from the first vector, and 16803the remaining elements from ``%vec2``. 16804 16805These intrinsics work for both fixed and scalable vectors. While this intrinsic 16806is marked as experimental, the recommended way to express this operation for 16807fixed-width vectors is still to use a shufflevector, as that may allow for more 16808optimization opportunities. 16809 16810For example: 16811 16812.. code-block:: text 16813 16814 llvm.experimental.vector.splice(<A,B,C,D>, <E,F,G,H>, 1) ==> <B, C, D, E> ; index 16815 llvm.experimental.vector.splice(<A,B,C,D>, <E,F,G,H>, -3) ==> <B, C, D, E> ; trailing elements 16816 16817 16818Arguments: 16819"""""""""" 16820 16821The first two operands are vectors with the same type. The third argument 16822``imm`` is the start index, modulo VL, where VL is the runtime vector length of 16823the source/result vector. The ``imm`` is a signed integer constant in the range 16824``-VL <= imm < VL``. For values outside of this range the result is poison. 16825 16826'``llvm.experimental.stepvector``' Intrinsic 16827^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16828 16829This is an overloaded intrinsic. You can use ``llvm.experimental.stepvector`` 16830to generate a vector whose lane values comprise the linear sequence 16831<0, 1, 2, ...>. It is primarily intended for scalable vectors. 16832 16833:: 16834 16835 declare <vscale x 4 x i32> @llvm.experimental.stepvector.nxv4i32() 16836 declare <vscale x 8 x i16> @llvm.experimental.stepvector.nxv8i16() 16837 16838The '``llvm.experimental.stepvector``' intrinsics are used to create vectors 16839of integers whose elements contain a linear sequence of values starting from 0 16840with a step of 1. This experimental intrinsic can only be used for vectors 16841with integer elements that are at least 8 bits in size. If the sequence value 16842exceeds the allowed limit for the element type then the result for that lane is 16843undefined. 16844 16845These intrinsics work for both fixed and scalable vectors. While this intrinsic 16846is marked as experimental, the recommended way to express this operation for 16847fixed-width vectors is still to generate a constant vector instead. 16848 16849 16850Arguments: 16851"""""""""" 16852 16853None. 16854 16855 16856Matrix Intrinsics 16857----------------- 16858 16859Operations on matrixes requiring shape information (like number of rows/columns 16860or the memory layout) can be expressed using the matrix intrinsics. These 16861intrinsics require matrix dimensions to be passed as immediate arguments, and 16862matrixes are passed and returned as vectors. This means that for a ``R`` x 16863``C`` matrix, element ``i`` of column ``j`` is at index ``j * R + i`` in the 16864corresponding vector, with indices starting at 0. Currently column-major layout 16865is assumed. The intrinsics support both integer and floating point matrixes. 16866 16867 16868'``llvm.matrix.transpose.*``' Intrinsic 16869^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16870 16871Syntax: 16872""""""" 16873This is an overloaded intrinsic. 16874 16875:: 16876 16877 declare vectorty @llvm.matrix.transpose.*(vectorty %In, i32 <Rows>, i32 <Cols>) 16878 16879Overview: 16880""""""""" 16881 16882The '``llvm.matrix.transpose.*``' intrinsics treat ``%In`` as a ``<Rows> x 16883<Cols>`` matrix and return the transposed matrix in the result vector. 16884 16885Arguments: 16886"""""""""" 16887 16888The first argument ``%In`` is a vector that corresponds to a ``<Rows> x 16889<Cols>`` matrix. Thus, arguments ``<Rows>`` and ``<Cols>`` correspond to the 16890number of rows and columns, respectively, and must be positive, constant 16891integers. The returned vector must have ``<Rows> * <Cols>`` elements, and have 16892the same float or integer element type as ``%In``. 16893 16894'``llvm.matrix.multiply.*``' Intrinsic 16895^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16896 16897Syntax: 16898""""""" 16899This is an overloaded intrinsic. 16900 16901:: 16902 16903 declare vectorty @llvm.matrix.multiply.*(vectorty %A, vectorty %B, i32 <OuterRows>, i32 <Inner>, i32 <OuterColumns>) 16904 16905Overview: 16906""""""""" 16907 16908The '``llvm.matrix.multiply.*``' intrinsics treat ``%A`` as a ``<OuterRows> x 16909<Inner>`` matrix, ``%B`` as a ``<Inner> x <OuterColumns>`` matrix, and 16910multiplies them. The result matrix is returned in the result vector. 16911 16912Arguments: 16913"""""""""" 16914 16915The first vector argument ``%A`` corresponds to a matrix with ``<OuterRows> * 16916<Inner>`` elements, and the second argument ``%B`` to a matrix with 16917``<Inner> * <OuterColumns>`` elements. Arguments ``<OuterRows>``, 16918``<Inner>`` and ``<OuterColumns>`` must be positive, constant integers. The 16919returned vector must have ``<OuterRows> * <OuterColumns>`` elements. 16920Vectors ``%A``, ``%B``, and the returned vector all have the same float or 16921integer element type. 16922 16923 16924'``llvm.matrix.column.major.load.*``' Intrinsic 16925^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16926 16927Syntax: 16928""""""" 16929This is an overloaded intrinsic. 16930 16931:: 16932 16933 declare vectorty @llvm.matrix.column.major.load.*( 16934 ptrty %Ptr, i64 %Stride, i1 <IsVolatile>, i32 <Rows>, i32 <Cols>) 16935 16936Overview: 16937""""""""" 16938 16939The '``llvm.matrix.column.major.load.*``' intrinsics load a ``<Rows> x <Cols>`` 16940matrix using a stride of ``%Stride`` to compute the start address of the 16941different columns. This allows for convenient loading of sub matrixes. If 16942``<IsVolatile>`` is true, the intrinsic is considered a :ref:`volatile memory 16943access <volatile>`. The result matrix is returned in the result vector. If the 16944``%Ptr`` argument is known to be aligned to some boundary, this can be 16945specified as an attribute on the argument. 16946 16947Arguments: 16948"""""""""" 16949 16950The first argument ``%Ptr`` is a pointer type to the returned vector type, and 16951corresponds to the start address to load from. The second argument ``%Stride`` 16952is a positive, constant integer with ``%Stride >= <Rows>``. ``%Stride`` is used 16953to compute the column memory addresses. I.e., for a column ``C``, its start 16954memory addresses is calculated with ``%Ptr + C * %Stride``. The third Argument 16955``<IsVolatile>`` is a boolean value. The fourth and fifth arguments, 16956``<Rows>`` and ``<Cols>``, correspond to the number of rows and columns, 16957respectively, and must be positive, constant integers. The returned vector must 16958have ``<Rows> * <Cols>`` elements. 16959 16960The :ref:`align <attr_align>` parameter attribute can be provided for the 16961``%Ptr`` arguments. 16962 16963 16964'``llvm.matrix.column.major.store.*``' Intrinsic 16965^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16966 16967Syntax: 16968""""""" 16969 16970:: 16971 16972 declare void @llvm.matrix.column.major.store.*( 16973 vectorty %In, ptrty %Ptr, i64 %Stride, i1 <IsVolatile>, i32 <Rows>, i32 <Cols>) 16974 16975Overview: 16976""""""""" 16977 16978The '``llvm.matrix.column.major.store.*``' intrinsics store the ``<Rows> x 16979<Cols>`` matrix in ``%In`` to memory using a stride of ``%Stride`` between 16980columns. If ``<IsVolatile>`` is true, the intrinsic is considered a 16981:ref:`volatile memory access <volatile>`. 16982 16983If the ``%Ptr`` argument is known to be aligned to some boundary, this can be 16984specified as an attribute on the argument. 16985 16986Arguments: 16987"""""""""" 16988 16989The first argument ``%In`` is a vector that corresponds to a ``<Rows> x 16990<Cols>`` matrix to be stored to memory. The second argument ``%Ptr`` is a 16991pointer to the vector type of ``%In``, and is the start address of the matrix 16992in memory. The third argument ``%Stride`` is a positive, constant integer with 16993``%Stride >= <Rows>``. ``%Stride`` is used to compute the column memory 16994addresses. I.e., for a column ``C``, its start memory addresses is calculated 16995with ``%Ptr + C * %Stride``. The fourth argument ``<IsVolatile>`` is a boolean 16996value. The arguments ``<Rows>`` and ``<Cols>`` correspond to the number of rows 16997and columns, respectively, and must be positive, constant integers. 16998 16999The :ref:`align <attr_align>` parameter attribute can be provided 17000for the ``%Ptr`` arguments. 17001 17002 17003Half Precision Floating-Point Intrinsics 17004---------------------------------------- 17005 17006For most target platforms, half precision floating-point is a 17007storage-only format. This means that it is a dense encoding (in memory) 17008but does not support computation in the format. 17009 17010This means that code must first load the half-precision floating-point 17011value as an i16, then convert it to float with 17012:ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can 17013then be performed on the float value (including extending to double 17014etc). To store the value back to memory, it is first converted to float 17015if needed, then converted to i16 with 17016:ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an 17017i16 value. 17018 17019.. _int_convert_to_fp16: 17020 17021'``llvm.convert.to.fp16``' Intrinsic 17022^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17023 17024Syntax: 17025""""""" 17026 17027:: 17028 17029 declare i16 @llvm.convert.to.fp16.f32(float %a) 17030 declare i16 @llvm.convert.to.fp16.f64(double %a) 17031 17032Overview: 17033""""""""" 17034 17035The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a 17036conventional floating-point type to half precision floating-point format. 17037 17038Arguments: 17039"""""""""" 17040 17041The intrinsic function contains single argument - the value to be 17042converted. 17043 17044Semantics: 17045"""""""""" 17046 17047The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a 17048conventional floating-point format to half precision floating-point format. The 17049return value is an ``i16`` which contains the converted number. 17050 17051Examples: 17052""""""""" 17053 17054.. code-block:: llvm 17055 17056 %res = call i16 @llvm.convert.to.fp16.f32(float %a) 17057 store i16 %res, i16* @x, align 2 17058 17059.. _int_convert_from_fp16: 17060 17061'``llvm.convert.from.fp16``' Intrinsic 17062^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17063 17064Syntax: 17065""""""" 17066 17067:: 17068 17069 declare float @llvm.convert.from.fp16.f32(i16 %a) 17070 declare double @llvm.convert.from.fp16.f64(i16 %a) 17071 17072Overview: 17073""""""""" 17074 17075The '``llvm.convert.from.fp16``' intrinsic function performs a 17076conversion from half precision floating-point format to single precision 17077floating-point format. 17078 17079Arguments: 17080"""""""""" 17081 17082The intrinsic function contains single argument - the value to be 17083converted. 17084 17085Semantics: 17086"""""""""" 17087 17088The '``llvm.convert.from.fp16``' intrinsic function performs a 17089conversion from half single precision floating-point format to single 17090precision floating-point format. The input half-float value is 17091represented by an ``i16`` value. 17092 17093Examples: 17094""""""""" 17095 17096.. code-block:: llvm 17097 17098 %a = load i16, i16* @x, align 2 17099 %res = call float @llvm.convert.from.fp16(i16 %a) 17100 17101Saturating floating-point to integer conversions 17102------------------------------------------------ 17103 17104The ``fptoui`` and ``fptosi`` instructions return a 17105:ref:`poison value <poisonvalues>` if the rounded-towards-zero value is not 17106representable by the result type. These intrinsics provide an alternative 17107conversion, which will saturate towards the smallest and largest representable 17108integer values instead. 17109 17110'``llvm.fptoui.sat.*``' Intrinsic 17111^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17112 17113Syntax: 17114""""""" 17115 17116This is an overloaded intrinsic. You can use ``llvm.fptoui.sat`` on any 17117floating-point argument type and any integer result type, or vectors thereof. 17118Not all targets may support all types, however. 17119 17120:: 17121 17122 declare i32 @llvm.fptoui.sat.i32.f32(float %f) 17123 declare i19 @llvm.fptoui.sat.i19.f64(double %f) 17124 declare <4 x i100> @llvm.fptoui.sat.v4i100.v4f128(<4 x fp128> %f) 17125 17126Overview: 17127""""""""" 17128 17129This intrinsic converts the argument into an unsigned integer using saturating 17130semantics. 17131 17132Arguments: 17133"""""""""" 17134 17135The argument may be any floating-point or vector of floating-point type. The 17136return value may be any integer or vector of integer type. The number of vector 17137elements in argument and return must be the same. 17138 17139Semantics: 17140"""""""""" 17141 17142The conversion to integer is performed subject to the following rules: 17143 17144- If the argument is any NaN, zero is returned. 17145- If the argument is smaller than zero (this includes negative infinity), 17146 zero is returned. 17147- If the argument is larger than the largest representable unsigned integer of 17148 the result type (this includes positive infinity), the largest representable 17149 unsigned integer is returned. 17150- Otherwise, the result of rounding the argument towards zero is returned. 17151 17152Example: 17153"""""""" 17154 17155.. code-block:: text 17156 17157 %a = call i8 @llvm.fptoui.sat.i8.f32(float 123.9) ; yields i8: 123 17158 %b = call i8 @llvm.fptoui.sat.i8.f32(float -5.7) ; yields i8: 0 17159 %c = call i8 @llvm.fptoui.sat.i8.f32(float 377.0) ; yields i8: 255 17160 %d = call i8 @llvm.fptoui.sat.i8.f32(float 0xFFF8000000000000) ; yields i8: 0 17161 17162'``llvm.fptosi.sat.*``' Intrinsic 17163^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17164 17165Syntax: 17166""""""" 17167 17168This is an overloaded intrinsic. You can use ``llvm.fptosi.sat`` on any 17169floating-point argument type and any integer result type, or vectors thereof. 17170Not all targets may support all types, however. 17171 17172:: 17173 17174 declare i32 @llvm.fptosi.sat.i32.f32(float %f) 17175 declare i19 @llvm.fptosi.sat.i19.f64(double %f) 17176 declare <4 x i100> @llvm.fptosi.sat.v4i100.v4f128(<4 x fp128> %f) 17177 17178Overview: 17179""""""""" 17180 17181This intrinsic converts the argument into a signed integer using saturating 17182semantics. 17183 17184Arguments: 17185"""""""""" 17186 17187The argument may be any floating-point or vector of floating-point type. The 17188return value may be any integer or vector of integer type. The number of vector 17189elements in argument and return must be the same. 17190 17191Semantics: 17192"""""""""" 17193 17194The conversion to integer is performed subject to the following rules: 17195 17196- If the argument is any NaN, zero is returned. 17197- If the argument is smaller than the smallest representable signed integer of 17198 the result type (this includes negative infinity), the smallest 17199 representable signed integer is returned. 17200- If the argument is larger than the largest representable signed integer of 17201 the result type (this includes positive infinity), the largest representable 17202 signed integer is returned. 17203- Otherwise, the result of rounding the argument towards zero is returned. 17204 17205Example: 17206"""""""" 17207 17208.. code-block:: text 17209 17210 %a = call i8 @llvm.fptosi.sat.i8.f32(float 23.9) ; yields i8: 23 17211 %b = call i8 @llvm.fptosi.sat.i8.f32(float -130.8) ; yields i8: -128 17212 %c = call i8 @llvm.fptosi.sat.i8.f32(float 999.0) ; yields i8: 127 17213 %d = call i8 @llvm.fptosi.sat.i8.f32(float 0xFFF8000000000000) ; yields i8: 0 17214 17215.. _dbg_intrinsics: 17216 17217Debugger Intrinsics 17218------------------- 17219 17220The LLVM debugger intrinsics (which all start with ``llvm.dbg.`` 17221prefix), are described in the `LLVM Source Level 17222Debugging <SourceLevelDebugging.html#format-common-intrinsics>`_ 17223document. 17224 17225Exception Handling Intrinsics 17226----------------------------- 17227 17228The LLVM exception handling intrinsics (which all start with 17229``llvm.eh.`` prefix), are described in the `LLVM Exception 17230Handling <ExceptionHandling.html#format-common-intrinsics>`_ document. 17231 17232.. _int_trampoline: 17233 17234Trampoline Intrinsics 17235--------------------- 17236 17237These intrinsics make it possible to excise one parameter, marked with 17238the :ref:`nest <nest>` attribute, from a function. The result is a 17239callable function pointer lacking the nest parameter - the caller does 17240not need to provide a value for it. Instead, the value to use is stored 17241in advance in a "trampoline", a block of memory usually allocated on the 17242stack, which also contains code to splice the nest value into the 17243argument list. This is used to implement the GCC nested function address 17244extension. 17245 17246For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)`` 17247then the resulting function pointer has signature ``i32 (i32, i32)*``. 17248It can be created as follows: 17249 17250.. code-block:: llvm 17251 17252 %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 17253 %tramp1 = getelementptr [10 x i8], [10 x i8]* %tramp, i32 0, i32 0 17254 call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval) 17255 %p = call i8* @llvm.adjust.trampoline(i8* %tramp1) 17256 %fp = bitcast i8* %p to i32 (i32, i32)* 17257 17258The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to 17259``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``. 17260 17261.. _int_it: 17262 17263'``llvm.init.trampoline``' Intrinsic 17264^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17265 17266Syntax: 17267""""""" 17268 17269:: 17270 17271 declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) 17272 17273Overview: 17274""""""""" 17275 17276This fills the memory pointed to by ``tramp`` with executable code, 17277turning it into a trampoline. 17278 17279Arguments: 17280"""""""""" 17281 17282The ``llvm.init.trampoline`` intrinsic takes three arguments, all 17283pointers. The ``tramp`` argument must point to a sufficiently large and 17284sufficiently aligned block of memory; this memory is written to by the 17285intrinsic. Note that the size and the alignment are target-specific - 17286LLVM currently provides no portable way of determining them, so a 17287front-end that generates this intrinsic needs to have some 17288target-specific knowledge. The ``func`` argument must hold a function 17289bitcast to an ``i8*``. 17290 17291Semantics: 17292"""""""""" 17293 17294The block of memory pointed to by ``tramp`` is filled with target 17295dependent code, turning it into a function. Then ``tramp`` needs to be 17296passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can 17297be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new 17298function's signature is the same as that of ``func`` with any arguments 17299marked with the ``nest`` attribute removed. At most one such ``nest`` 17300argument is allowed, and it must be of pointer type. Calling the new 17301function is equivalent to calling ``func`` with the same argument list, 17302but with ``nval`` used for the missing ``nest`` argument. If, after 17303calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is 17304modified, then the effect of any later call to the returned function 17305pointer is undefined. 17306 17307.. _int_at: 17308 17309'``llvm.adjust.trampoline``' Intrinsic 17310^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17311 17312Syntax: 17313""""""" 17314 17315:: 17316 17317 declare i8* @llvm.adjust.trampoline(i8* <tramp>) 17318 17319Overview: 17320""""""""" 17321 17322This performs any required machine-specific adjustment to the address of 17323a trampoline (passed as ``tramp``). 17324 17325Arguments: 17326"""""""""" 17327 17328``tramp`` must point to a block of memory which already has trampoline 17329code filled in by a previous call to 17330:ref:`llvm.init.trampoline <int_it>`. 17331 17332Semantics: 17333"""""""""" 17334 17335On some architectures the address of the code to be executed needs to be 17336different than the address where the trampoline is actually stored. This 17337intrinsic returns the executable address corresponding to ``tramp`` 17338after performing the required machine specific adjustments. The pointer 17339returned can then be :ref:`bitcast and executed <int_trampoline>`. 17340 17341 17342.. _int_vp: 17343 17344Vector Predication Intrinsics 17345----------------------------- 17346VP intrinsics are intended for predicated SIMD/vector code. A typical VP 17347operation takes a vector mask and an explicit vector length parameter as in: 17348 17349:: 17350 17351 <W x T> llvm.vp.<opcode>.*(<W x T> %x, <W x T> %y, <W x i1> %mask, i32 %evl) 17352 17353The vector mask parameter (%mask) always has a vector of `i1` type, for example 17354`<32 x i1>`. The explicit vector length parameter always has the type `i32` and 17355is an unsigned integer value. The explicit vector length parameter (%evl) is in 17356the range: 17357 17358:: 17359 17360 0 <= %evl <= W, where W is the number of vector elements 17361 17362Note that for :ref:`scalable vector types <t_vector>` ``W`` is the runtime 17363length of the vector. 17364 17365The VP intrinsic has undefined behavior if ``%evl > W``. The explicit vector 17366length (%evl) creates a mask, %EVLmask, with all elements ``0 <= i < %evl`` set 17367to True, and all other lanes ``%evl <= i < W`` to False. A new mask %M is 17368calculated with an element-wise AND from %mask and %EVLmask: 17369 17370:: 17371 17372 M = %mask AND %EVLmask 17373 17374A vector operation ``<opcode>`` on vectors ``A`` and ``B`` calculates: 17375 17376:: 17377 17378 A <opcode> B = { A[i] <opcode> B[i] M[i] = True, and 17379 { undef otherwise 17380 17381Optimization Hint 17382^^^^^^^^^^^^^^^^^ 17383 17384Some targets, such as AVX512, do not support the %evl parameter in hardware. 17385The use of an effective %evl is discouraged for those targets. The function 17386``TargetTransformInfo::hasActiveVectorLength()`` returns true when the target 17387has native support for %evl. 17388 17389 17390.. _int_vp_add: 17391 17392'``llvm.vp.add.*``' Intrinsics 17393^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17394 17395Syntax: 17396""""""" 17397This is an overloaded intrinsic. 17398 17399:: 17400 17401 declare <16 x i32> @llvm.vp.add.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17402 declare <vscale x 4 x i32> @llvm.vp.add.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17403 declare <256 x i64> @llvm.vp.add.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17404 17405Overview: 17406""""""""" 17407 17408Predicated integer addition of two vectors of integers. 17409 17410 17411Arguments: 17412"""""""""" 17413 17414The first two operands and the result have the same vector of integer type. The 17415third operand is the vector mask and has the same number of elements as the 17416result vector type. The fourth operand is the explicit vector length of the 17417operation. 17418 17419Semantics: 17420"""""""""" 17421 17422The '``llvm.vp.add``' intrinsic performs integer addition (:ref:`add <i_add>`) 17423of the first and second vector operand on each enabled lane. The result on 17424disabled lanes is undefined. 17425 17426Examples: 17427""""""""" 17428 17429.. code-block:: llvm 17430 17431 %r = call <4 x i32> @llvm.vp.add.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17432 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17433 17434 %t = add <4 x i32> %a, %b 17435 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17436 17437.. _int_vp_sub: 17438 17439'``llvm.vp.sub.*``' Intrinsics 17440^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17441 17442Syntax: 17443""""""" 17444This is an overloaded intrinsic. 17445 17446:: 17447 17448 declare <16 x i32> @llvm.vp.sub.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17449 declare <vscale x 4 x i32> @llvm.vp.sub.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17450 declare <256 x i64> @llvm.vp.sub.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17451 17452Overview: 17453""""""""" 17454 17455Predicated integer subtraction of two vectors of integers. 17456 17457 17458Arguments: 17459"""""""""" 17460 17461The first two operands and the result have the same vector of integer type. The 17462third operand is the vector mask and has the same number of elements as the 17463result vector type. The fourth operand is the explicit vector length of the 17464operation. 17465 17466Semantics: 17467"""""""""" 17468 17469The '``llvm.vp.sub``' intrinsic performs integer subtraction 17470(:ref:`sub <i_sub>`) of the first and second vector operand on each enabled 17471lane. The result on disabled lanes is undefined. 17472 17473Examples: 17474""""""""" 17475 17476.. code-block:: llvm 17477 17478 %r = call <4 x i32> @llvm.vp.sub.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17479 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17480 17481 %t = sub <4 x i32> %a, %b 17482 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17483 17484 17485 17486.. _int_vp_mul: 17487 17488'``llvm.vp.mul.*``' Intrinsics 17489^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17490 17491Syntax: 17492""""""" 17493This is an overloaded intrinsic. 17494 17495:: 17496 17497 declare <16 x i32> @llvm.vp.mul.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17498 declare <vscale x 4 x i32> @llvm.vp.mul.nxv46i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17499 declare <256 x i64> @llvm.vp.mul.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17500 17501Overview: 17502""""""""" 17503 17504Predicated integer multiplication of two vectors of integers. 17505 17506 17507Arguments: 17508"""""""""" 17509 17510The first two operands and the result have the same vector of integer type. The 17511third operand is the vector mask and has the same number of elements as the 17512result vector type. The fourth operand is the explicit vector length of the 17513operation. 17514 17515Semantics: 17516"""""""""" 17517The '``llvm.vp.mul``' intrinsic performs integer multiplication 17518(:ref:`mul <i_mul>`) of the first and second vector operand on each enabled 17519lane. The result on disabled lanes is undefined. 17520 17521Examples: 17522""""""""" 17523 17524.. code-block:: llvm 17525 17526 %r = call <4 x i32> @llvm.vp.mul.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17527 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17528 17529 %t = mul <4 x i32> %a, %b 17530 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17531 17532 17533.. _int_vp_sdiv: 17534 17535'``llvm.vp.sdiv.*``' Intrinsics 17536^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17537 17538Syntax: 17539""""""" 17540This is an overloaded intrinsic. 17541 17542:: 17543 17544 declare <16 x i32> @llvm.vp.sdiv.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17545 declare <vscale x 4 x i32> @llvm.vp.sdiv.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17546 declare <256 x i64> @llvm.vp.sdiv.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17547 17548Overview: 17549""""""""" 17550 17551Predicated, signed division of two vectors of integers. 17552 17553 17554Arguments: 17555"""""""""" 17556 17557The first two operands and the result have the same vector of integer type. The 17558third operand is the vector mask and has the same number of elements as the 17559result vector type. The fourth operand is the explicit vector length of the 17560operation. 17561 17562Semantics: 17563"""""""""" 17564 17565The '``llvm.vp.sdiv``' intrinsic performs signed division (:ref:`sdiv <i_sdiv>`) 17566of the first and second vector operand on each enabled lane. The result on 17567disabled lanes is undefined. 17568 17569Examples: 17570""""""""" 17571 17572.. code-block:: llvm 17573 17574 %r = call <4 x i32> @llvm.vp.sdiv.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17575 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17576 17577 %t = sdiv <4 x i32> %a, %b 17578 %also.r = select <4 x ii> %mask, <4 x i32> %t, <4 x i32> undef 17579 17580 17581.. _int_vp_udiv: 17582 17583'``llvm.vp.udiv.*``' Intrinsics 17584^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17585 17586Syntax: 17587""""""" 17588This is an overloaded intrinsic. 17589 17590:: 17591 17592 declare <16 x i32> @llvm.vp.udiv.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17593 declare <vscale x 4 x i32> @llvm.vp.udiv.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17594 declare <256 x i64> @llvm.vp.udiv.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17595 17596Overview: 17597""""""""" 17598 17599Predicated, unsigned division of two vectors of integers. 17600 17601 17602Arguments: 17603"""""""""" 17604 17605The first two operands and the result have the same vector of integer type. The third operand is the vector mask and has the same number of elements as the result vector type. The fourth operand is the explicit vector length of the operation. 17606 17607Semantics: 17608"""""""""" 17609 17610The '``llvm.vp.udiv``' intrinsic performs unsigned division 17611(:ref:`udiv <i_udiv>`) of the first and second vector operand on each enabled 17612lane. The result on disabled lanes is undefined. 17613 17614Examples: 17615""""""""" 17616 17617.. code-block:: llvm 17618 17619 %r = call <4 x i32> @llvm.vp.udiv.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17620 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17621 17622 %t = udiv <4 x i32> %a, %b 17623 %also.r = select <4 x ii> %mask, <4 x i32> %t, <4 x i32> undef 17624 17625 17626 17627.. _int_vp_srem: 17628 17629'``llvm.vp.srem.*``' Intrinsics 17630^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17631 17632Syntax: 17633""""""" 17634This is an overloaded intrinsic. 17635 17636:: 17637 17638 declare <16 x i32> @llvm.vp.srem.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17639 declare <vscale x 4 x i32> @llvm.vp.srem.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17640 declare <256 x i64> @llvm.vp.srem.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17641 17642Overview: 17643""""""""" 17644 17645Predicated computations of the signed remainder of two integer vectors. 17646 17647 17648Arguments: 17649"""""""""" 17650 17651The first two operands and the result have the same vector of integer type. The 17652third operand is the vector mask and has the same number of elements as the 17653result vector type. The fourth operand is the explicit vector length of the 17654operation. 17655 17656Semantics: 17657"""""""""" 17658 17659The '``llvm.vp.srem``' intrinsic computes the remainder of the signed division 17660(:ref:`srem <i_srem>`) of the first and second vector operand on each enabled 17661lane. The result on disabled lanes is undefined. 17662 17663Examples: 17664""""""""" 17665 17666.. code-block:: llvm 17667 17668 %r = call <4 x i32> @llvm.vp.srem.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17669 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17670 17671 %t = srem <4 x i32> %a, %b 17672 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17673 17674 17675 17676.. _int_vp_urem: 17677 17678'``llvm.vp.urem.*``' Intrinsics 17679^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17680 17681Syntax: 17682""""""" 17683This is an overloaded intrinsic. 17684 17685:: 17686 17687 declare <16 x i32> @llvm.vp.urem.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17688 declare <vscale x 4 x i32> @llvm.vp.urem.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17689 declare <256 x i64> @llvm.vp.urem.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17690 17691Overview: 17692""""""""" 17693 17694Predicated computation of the unsigned remainder of two integer vectors. 17695 17696 17697Arguments: 17698"""""""""" 17699 17700The first two operands and the result have the same vector of integer type. The 17701third operand is the vector mask and has the same number of elements as the 17702result vector type. The fourth operand is the explicit vector length of the 17703operation. 17704 17705Semantics: 17706"""""""""" 17707 17708The '``llvm.vp.urem``' intrinsic computes the remainder of the unsigned division 17709(:ref:`urem <i_urem>`) of the first and second vector operand on each enabled 17710lane. The result on disabled lanes is undefined. 17711 17712Examples: 17713""""""""" 17714 17715.. code-block:: llvm 17716 17717 %r = call <4 x i32> @llvm.vp.urem.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17718 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17719 17720 %t = urem <4 x i32> %a, %b 17721 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17722 17723 17724.. _int_vp_ashr: 17725 17726'``llvm.vp.ashr.*``' Intrinsics 17727^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17728 17729Syntax: 17730""""""" 17731This is an overloaded intrinsic. 17732 17733:: 17734 17735 declare <16 x i32> @llvm.vp.ashr.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17736 declare <vscale x 4 x i32> @llvm.vp.ashr.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17737 declare <256 x i64> @llvm.vp.ashr.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17738 17739Overview: 17740""""""""" 17741 17742Vector-predicated arithmetic right-shift. 17743 17744 17745Arguments: 17746"""""""""" 17747 17748The first two operands and the result have the same vector of integer type. The 17749third operand is the vector mask and has the same number of elements as the 17750result vector type. The fourth operand is the explicit vector length of the 17751operation. 17752 17753Semantics: 17754"""""""""" 17755 17756The '``llvm.vp.ashr``' intrinsic computes the arithmetic right shift 17757(:ref:`ashr <i_ashr>`) of the first operand by the second operand on each 17758enabled lane. The result on disabled lanes is undefined. 17759 17760Examples: 17761""""""""" 17762 17763.. code-block:: llvm 17764 17765 %r = call <4 x i32> @llvm.vp.ashr.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17766 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17767 17768 %t = ashr <4 x i32> %a, %b 17769 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17770 17771 17772.. _int_vp_lshr: 17773 17774 17775'``llvm.vp.lshr.*``' Intrinsics 17776^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17777 17778Syntax: 17779""""""" 17780This is an overloaded intrinsic. 17781 17782:: 17783 17784 declare <16 x i32> @llvm.vp.lshr.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17785 declare <vscale x 4 x i32> @llvm.vp.lshr.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17786 declare <256 x i64> @llvm.vp.lshr.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17787 17788Overview: 17789""""""""" 17790 17791Vector-predicated logical right-shift. 17792 17793 17794Arguments: 17795"""""""""" 17796 17797The first two operands and the result have the same vector of integer type. The 17798third operand is the vector mask and has the same number of elements as the 17799result vector type. The fourth operand is the explicit vector length of the 17800operation. 17801 17802Semantics: 17803"""""""""" 17804 17805The '``llvm.vp.lshr``' intrinsic computes the logical right shift 17806(:ref:`lshr <i_lshr>`) of the first operand by the second operand on each 17807enabled lane. The result on disabled lanes is undefined. 17808 17809Examples: 17810""""""""" 17811 17812.. code-block:: llvm 17813 17814 %r = call <4 x i32> @llvm.vp.lshr.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17815 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17816 17817 %t = lshr <4 x i32> %a, %b 17818 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17819 17820 17821.. _int_vp_shl: 17822 17823'``llvm.vp.shl.*``' Intrinsics 17824^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17825 17826Syntax: 17827""""""" 17828This is an overloaded intrinsic. 17829 17830:: 17831 17832 declare <16 x i32> @llvm.vp.shl.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17833 declare <vscale x 4 x i32> @llvm.vp.shl.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17834 declare <256 x i64> @llvm.vp.shl.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17835 17836Overview: 17837""""""""" 17838 17839Vector-predicated left shift. 17840 17841 17842Arguments: 17843"""""""""" 17844 17845The first two operands and the result have the same vector of integer type. The 17846third operand is the vector mask and has the same number of elements as the 17847result vector type. The fourth operand is the explicit vector length of the 17848operation. 17849 17850Semantics: 17851"""""""""" 17852 17853The '``llvm.vp.shl``' intrinsic computes the left shift (:ref:`shl <i_shl>`) of 17854the first operand by the second operand on each enabled lane. The result on 17855disabled lanes is undefined. 17856 17857Examples: 17858""""""""" 17859 17860.. code-block:: llvm 17861 17862 %r = call <4 x i32> @llvm.vp.shl.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17863 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17864 17865 %t = shl <4 x i32> %a, %b 17866 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17867 17868 17869.. _int_vp_or: 17870 17871'``llvm.vp.or.*``' Intrinsics 17872^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17873 17874Syntax: 17875""""""" 17876This is an overloaded intrinsic. 17877 17878:: 17879 17880 declare <16 x i32> @llvm.vp.or.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17881 declare <vscale x 4 x i32> @llvm.vp.or.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17882 declare <256 x i64> @llvm.vp.or.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17883 17884Overview: 17885""""""""" 17886 17887Vector-predicated or. 17888 17889 17890Arguments: 17891"""""""""" 17892 17893The first two operands and the result have the same vector of integer type. The 17894third operand is the vector mask and has the same number of elements as the 17895result vector type. The fourth operand is the explicit vector length of the 17896operation. 17897 17898Semantics: 17899"""""""""" 17900 17901The '``llvm.vp.or``' intrinsic performs a bitwise or (:ref:`or <i_or>`) of the 17902first two operands on each enabled lane. The result on disabled lanes is 17903undefined. 17904 17905Examples: 17906""""""""" 17907 17908.. code-block:: llvm 17909 17910 %r = call <4 x i32> @llvm.vp.or.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17911 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17912 17913 %t = or <4 x i32> %a, %b 17914 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17915 17916 17917.. _int_vp_and: 17918 17919'``llvm.vp.and.*``' Intrinsics 17920^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17921 17922Syntax: 17923""""""" 17924This is an overloaded intrinsic. 17925 17926:: 17927 17928 declare <16 x i32> @llvm.vp.and.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17929 declare <vscale x 4 x i32> @llvm.vp.and.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17930 declare <256 x i64> @llvm.vp.and.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17931 17932Overview: 17933""""""""" 17934 17935Vector-predicated and. 17936 17937 17938Arguments: 17939"""""""""" 17940 17941The first two operands and the result have the same vector of integer type. The 17942third operand is the vector mask and has the same number of elements as the 17943result vector type. The fourth operand is the explicit vector length of the 17944operation. 17945 17946Semantics: 17947"""""""""" 17948 17949The '``llvm.vp.and``' intrinsic performs a bitwise and (:ref:`and <i_or>`) of 17950the first two operands on each enabled lane. The result on disabled lanes is 17951undefined. 17952 17953Examples: 17954""""""""" 17955 17956.. code-block:: llvm 17957 17958 %r = call <4 x i32> @llvm.vp.and.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 17959 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 17960 17961 %t = and <4 x i32> %a, %b 17962 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 17963 17964 17965.. _int_vp_xor: 17966 17967'``llvm.vp.xor.*``' Intrinsics 17968^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17969 17970Syntax: 17971""""""" 17972This is an overloaded intrinsic. 17973 17974:: 17975 17976 declare <16 x i32> @llvm.vp.xor.v16i32 (<16 x i32> <left_op>, <16 x i32> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 17977 declare <vscale x 4 x i32> @llvm.vp.xor.nxv4i32 (<vscale x 4 x i32> <left_op>, <vscale x 4 x i32> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 17978 declare <256 x i64> @llvm.vp.xor.v256i64 (<256 x i64> <left_op>, <256 x i64> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 17979 17980Overview: 17981""""""""" 17982 17983Vector-predicated, bitwise xor. 17984 17985 17986Arguments: 17987"""""""""" 17988 17989The first two operands and the result have the same vector of integer type. The 17990third operand is the vector mask and has the same number of elements as the 17991result vector type. The fourth operand is the explicit vector length of the 17992operation. 17993 17994Semantics: 17995"""""""""" 17996 17997The '``llvm.vp.xor``' intrinsic performs a bitwise xor (:ref:`xor <i_xor>`) of 17998the first two operands on each enabled lane. 17999The result on disabled lanes is undefined. 18000 18001Examples: 18002""""""""" 18003 18004.. code-block:: llvm 18005 18006 %r = call <4 x i32> @llvm.vp.xor.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18007 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18008 18009 %t = xor <4 x i32> %a, %b 18010 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18011 18012 18013.. _int_get_active_lane_mask: 18014 18015'``llvm.get.active.lane.mask.*``' Intrinsics 18016^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18017 18018Syntax: 18019""""""" 18020This is an overloaded intrinsic. 18021 18022:: 18023 18024 declare <4 x i1> @llvm.get.active.lane.mask.v4i1.i32(i32 %base, i32 %n) 18025 declare <8 x i1> @llvm.get.active.lane.mask.v8i1.i64(i64 %base, i64 %n) 18026 declare <16 x i1> @llvm.get.active.lane.mask.v16i1.i64(i64 %base, i64 %n) 18027 declare <vscale x 16 x i1> @llvm.get.active.lane.mask.nxv16i1.i64(i64 %base, i64 %n) 18028 18029 18030Overview: 18031""""""""" 18032 18033Create a mask representing active and inactive vector lanes. 18034 18035 18036Arguments: 18037"""""""""" 18038 18039Both operands have the same scalar integer type. The result is a vector with 18040the i1 element type. 18041 18042Semantics: 18043"""""""""" 18044 18045The '``llvm.get.active.lane.mask.*``' intrinsics are semantically equivalent 18046to: 18047 18048:: 18049 18050 %m[i] = icmp ult (%base + i), %n 18051 18052where ``%m`` is a vector (mask) of active/inactive lanes with its elements 18053indexed by ``i``, and ``%base``, ``%n`` are the two arguments to 18054``llvm.get.active.lane.mask.*``, ``%icmp`` is an integer compare and ``ult`` 18055the unsigned less-than comparison operator. Overflow cannot occur in 18056``(%base + i)`` and its comparison against ``%n`` as it is performed in integer 18057numbers and not in machine numbers. If ``%n`` is ``0``, then the result is a 18058poison value. The above is equivalent to: 18059 18060:: 18061 18062 %m = @llvm.get.active.lane.mask(%base, %n) 18063 18064This can, for example, be emitted by the loop vectorizer in which case 18065``%base`` is the first element of the vector induction variable (VIV) and 18066``%n`` is the loop tripcount. Thus, these intrinsics perform an element-wise 18067less than comparison of VIV with the loop tripcount, producing a mask of 18068true/false values representing active/inactive vector lanes, except if the VIV 18069overflows in which case they return false in the lanes where the VIV overflows. 18070The arguments are scalar types to accommodate scalable vector types, for which 18071it is unknown what the type of the step vector needs to be that enumerate its 18072lanes without overflow. 18073 18074This mask ``%m`` can e.g. be used in masked load/store instructions. These 18075intrinsics provide a hint to the backend. I.e., for a vector loop, the 18076back-edge taken count of the original scalar loop is explicit as the second 18077argument. 18078 18079 18080Examples: 18081""""""""" 18082 18083.. code-block:: llvm 18084 18085 %active.lane.mask = call <4 x i1> @llvm.get.active.lane.mask.v4i1.i64(i64 %elem0, i64 429) 18086 %wide.masked.load = call <4 x i32> @llvm.masked.load.v4i32.p0v4i32(<4 x i32>* %3, i32 4, <4 x i1> %active.lane.mask, <4 x i32> undef) 18087 18088 18089.. _int_mload_mstore: 18090 18091Masked Vector Load and Store Intrinsics 18092--------------------------------------- 18093 18094LLVM 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. 18095 18096.. _int_mload: 18097 18098'``llvm.masked.load.*``' Intrinsics 18099^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18100 18101Syntax: 18102""""""" 18103This is an overloaded intrinsic. The loaded data is a vector of any integer, floating-point or pointer data type. 18104 18105:: 18106 18107 declare <16 x float> @llvm.masked.load.v16f32.p0v16f32 (<16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>) 18108 declare <2 x double> @llvm.masked.load.v2f64.p0v2f64 (<2 x double>* <ptr>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>) 18109 ;; The data is a vector of pointers to double 18110 declare <8 x double*> @llvm.masked.load.v8p0f64.p0v8p0f64 (<8 x double*>* <ptr>, i32 <alignment>, <8 x i1> <mask>, <8 x double*> <passthru>) 18111 ;; The data is a vector of function pointers 18112 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>) 18113 18114Overview: 18115""""""""" 18116 18117Reads 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. 18118 18119 18120Arguments: 18121"""""""""" 18122 18123The first operand is the base pointer for the load. The second operand is the alignment of the source location. It must be a power of two 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. 18124 18125Semantics: 18126"""""""""" 18127 18128The '``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. 18129The 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. 18130 18131 18132:: 18133 18134 %res = call <16 x float> @llvm.masked.load.v16f32.p0v16f32 (<16 x float>* %ptr, i32 4, <16 x i1>%mask, <16 x float> %passthru) 18135 18136 ;; The result of the two following instructions is identical aside from potential memory access exception 18137 %loadlal = load <16 x float>, <16 x float>* %ptr, align 4 18138 %res = select <16 x i1> %mask, <16 x float> %loadlal, <16 x float> %passthru 18139 18140.. _int_mstore: 18141 18142'``llvm.masked.store.*``' Intrinsics 18143^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18144 18145Syntax: 18146""""""" 18147This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type. 18148 18149:: 18150 18151 declare void @llvm.masked.store.v8i32.p0v8i32 (<8 x i32> <value>, <8 x i32>* <ptr>, i32 <alignment>, <8 x i1> <mask>) 18152 declare void @llvm.masked.store.v16f32.p0v16f32 (<16 x float> <value>, <16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>) 18153 ;; The data is a vector of pointers to double 18154 declare void @llvm.masked.store.v8p0f64.p0v8p0f64 (<8 x double*> <value>, <8 x double*>* <ptr>, i32 <alignment>, <8 x i1> <mask>) 18155 ;; The data is a vector of function pointers 18156 declare void @llvm.masked.store.v4p0f_i32f.p0v4p0f_i32f (<4 x i32 ()*> <value>, <4 x i32 ()*>* <ptr>, i32 <alignment>, <4 x i1> <mask>) 18157 18158Overview: 18159""""""""" 18160 18161Writes 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. 18162 18163Arguments: 18164"""""""""" 18165 18166The 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. It must be a power of two constant integer value. 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. 18167 18168 18169Semantics: 18170"""""""""" 18171 18172The '``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. 18173The 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. 18174 18175:: 18176 18177 call void @llvm.masked.store.v16f32.p0v16f32(<16 x float> %value, <16 x float>* %ptr, i32 4, <16 x i1> %mask) 18178 18179 ;; The result of the following instructions is identical aside from potential data races and memory access exceptions 18180 %oldval = load <16 x float>, <16 x float>* %ptr, align 4 18181 %res = select <16 x i1> %mask, <16 x float> %value, <16 x float> %oldval 18182 store <16 x float> %res, <16 x float>* %ptr, align 4 18183 18184 18185Masked Vector Gather and Scatter Intrinsics 18186------------------------------------------- 18187 18188LLVM 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. 18189 18190.. _int_mgather: 18191 18192'``llvm.masked.gather.*``' Intrinsics 18193^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18194 18195Syntax: 18196""""""" 18197This 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. 18198 18199:: 18200 18201 declare <16 x float> @llvm.masked.gather.v16f32.v16p0f32 (<16 x float*> <ptrs>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>) 18202 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>) 18203 declare <8 x float*> @llvm.masked.gather.v8p0f32.v8p0p0f32 (<8 x float**> <ptrs>, i32 <alignment>, <8 x i1> <mask>, <8 x float*> <passthru>) 18204 18205Overview: 18206""""""""" 18207 18208Reads 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. 18209 18210 18211Arguments: 18212"""""""""" 18213 18214The 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 0 or a power of two 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. 18215 18216Semantics: 18217"""""""""" 18218 18219The '``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. 18220The 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. 18221 18222 18223:: 18224 18225 %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) 18226 18227 ;; The gather with all-true mask is equivalent to the following instruction sequence 18228 %ptr0 = extractelement <4 x double*> %ptrs, i32 0 18229 %ptr1 = extractelement <4 x double*> %ptrs, i32 1 18230 %ptr2 = extractelement <4 x double*> %ptrs, i32 2 18231 %ptr3 = extractelement <4 x double*> %ptrs, i32 3 18232 18233 %val0 = load double, double* %ptr0, align 8 18234 %val1 = load double, double* %ptr1, align 8 18235 %val2 = load double, double* %ptr2, align 8 18236 %val3 = load double, double* %ptr3, align 8 18237 18238 %vec0 = insertelement <4 x double>undef, %val0, 0 18239 %vec01 = insertelement <4 x double>%vec0, %val1, 1 18240 %vec012 = insertelement <4 x double>%vec01, %val2, 2 18241 %vec0123 = insertelement <4 x double>%vec012, %val3, 3 18242 18243.. _int_mscatter: 18244 18245'``llvm.masked.scatter.*``' Intrinsics 18246^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18247 18248Syntax: 18249""""""" 18250This 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. 18251 18252:: 18253 18254 declare void @llvm.masked.scatter.v8i32.v8p0i32 (<8 x i32> <value>, <8 x i32*> <ptrs>, i32 <alignment>, <8 x i1> <mask>) 18255 declare void @llvm.masked.scatter.v16f32.v16p1f32 (<16 x float> <value>, <16 x float addrspace(1)*> <ptrs>, i32 <alignment>, <16 x i1> <mask>) 18256 declare void @llvm.masked.scatter.v4p0f64.v4p0p0f64 (<4 x double*> <value>, <4 x double**> <ptrs>, i32 <alignment>, <4 x i1> <mask>) 18257 18258Overview: 18259""""""""" 18260 18261Writes 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. 18262 18263Arguments: 18264"""""""""" 18265 18266The 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. It must be 0 or a power of two constant integer value. 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. 18267 18268Semantics: 18269"""""""""" 18270 18271The '``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. 18272 18273:: 18274 18275 ;; This instruction unconditionally stores data vector in multiple addresses 18276 call @llvm.masked.scatter.v8i32.v8p0i32 (<8 x i32> %value, <8 x i32*> %ptrs, i32 4, <8 x i1> <true, true, .. true>) 18277 18278 ;; It is equivalent to a list of scalar stores 18279 %val0 = extractelement <8 x i32> %value, i32 0 18280 %val1 = extractelement <8 x i32> %value, i32 1 18281 .. 18282 %val7 = extractelement <8 x i32> %value, i32 7 18283 %ptr0 = extractelement <8 x i32*> %ptrs, i32 0 18284 %ptr1 = extractelement <8 x i32*> %ptrs, i32 1 18285 .. 18286 %ptr7 = extractelement <8 x i32*> %ptrs, i32 7 18287 ;; Note: the order of the following stores is important when they overlap: 18288 store i32 %val0, i32* %ptr0, align 4 18289 store i32 %val1, i32* %ptr1, align 4 18290 .. 18291 store i32 %val7, i32* %ptr7, align 4 18292 18293 18294Masked Vector Expanding Load and Compressing Store Intrinsics 18295------------------------------------------------------------- 18296 18297LLVM 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>`. 18298 18299.. _int_expandload: 18300 18301'``llvm.masked.expandload.*``' Intrinsics 18302^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18303 18304Syntax: 18305""""""" 18306This 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. 18307 18308:: 18309 18310 declare <16 x float> @llvm.masked.expandload.v16f32 (float* <ptr>, <16 x i1> <mask>, <16 x float> <passthru>) 18311 declare <2 x i64> @llvm.masked.expandload.v2i64 (i64* <ptr>, <2 x i1> <mask>, <2 x i64> <passthru>) 18312 18313Overview: 18314""""""""" 18315 18316Reads 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', "expandload" 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. 18317 18318 18319Arguments: 18320"""""""""" 18321 18322The 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. 18323 18324Semantics: 18325"""""""""" 18326 18327The '``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: 18328 18329.. code-block:: c 18330 18331 // In this loop we load from B and spread the elements into array A. 18332 double *A, B; int *C; 18333 for (int i = 0; i < size; ++i) { 18334 if (C[i] != 0) 18335 A[i] = B[j++]; 18336 } 18337 18338 18339.. code-block:: llvm 18340 18341 ; Load several elements from array B and expand them in a vector. 18342 ; The number of loaded elements is equal to the number of '1' elements in the Mask. 18343 %Tmp = call <8 x double> @llvm.masked.expandload.v8f64(double* %Bptr, <8 x i1> %Mask, <8 x double> undef) 18344 ; Store the result in A 18345 call void @llvm.masked.store.v8f64.p0v8f64(<8 x double> %Tmp, <8 x double>* %Aptr, i32 8, <8 x i1> %Mask) 18346 18347 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask. 18348 %MaskI = bitcast <8 x i1> %Mask to i8 18349 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI) 18350 %MaskI64 = zext i8 %MaskIPopcnt to i64 18351 %BNextInd = add i64 %BInd, %MaskI64 18352 18353 18354Other targets may support this intrinsic differently, for example, by lowering it into a sequence of conditional scalar load operations and shuffles. 18355If all mask elements are '1', the intrinsic behavior is equivalent to the regular unmasked vector load. 18356 18357.. _int_compressstore: 18358 18359'``llvm.masked.compressstore.*``' Intrinsics 18360^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18361 18362Syntax: 18363""""""" 18364This 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. 18365 18366:: 18367 18368 declare void @llvm.masked.compressstore.v8i32 (<8 x i32> <value>, i32* <ptr>, <8 x i1> <mask>) 18369 declare void @llvm.masked.compressstore.v16f32 (<16 x float> <value>, float* <ptr>, <16 x i1> <mask>) 18370 18371Overview: 18372""""""""" 18373 18374Selects 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. 18375 18376Arguments: 18377"""""""""" 18378 18379The 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. 18380 18381 18382Semantics: 18383"""""""""" 18384 18385The '``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: 18386 18387.. code-block:: c 18388 18389 // In this loop we load elements from A and store them consecutively in B 18390 double *A, B; int *C; 18391 for (int i = 0; i < size; ++i) { 18392 if (C[i] != 0) 18393 B[j++] = A[i] 18394 } 18395 18396 18397.. code-block:: llvm 18398 18399 ; Load elements from A. 18400 %Tmp = call <8 x double> @llvm.masked.load.v8f64.p0v8f64(<8 x double>* %Aptr, i32 8, <8 x i1> %Mask, <8 x double> undef) 18401 ; Store all selected elements consecutively in array B 18402 call <void> @llvm.masked.compressstore.v8f64(<8 x double> %Tmp, double* %Bptr, <8 x i1> %Mask) 18403 18404 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask. 18405 %MaskI = bitcast <8 x i1> %Mask to i8 18406 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI) 18407 %MaskI64 = zext i8 %MaskIPopcnt to i64 18408 %BNextInd = add i64 %BInd, %MaskI64 18409 18410 18411Other targets may support this intrinsic differently, for example, by lowering it into a sequence of branches that guard scalar store operations. 18412 18413 18414Memory Use Markers 18415------------------ 18416 18417This class of intrinsics provides information about the 18418:ref:`lifetime of memory objects <objectlifetime>` and ranges where variables 18419are immutable. 18420 18421.. _int_lifestart: 18422 18423'``llvm.lifetime.start``' Intrinsic 18424^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18425 18426Syntax: 18427""""""" 18428 18429:: 18430 18431 declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>) 18432 18433Overview: 18434""""""""" 18435 18436The '``llvm.lifetime.start``' intrinsic specifies the start of a memory 18437object's lifetime. 18438 18439Arguments: 18440"""""""""" 18441 18442The first argument is a constant integer representing the size of the 18443object, or -1 if it is variable sized. The second argument is a pointer 18444to the object. 18445 18446Semantics: 18447"""""""""" 18448 18449If ``ptr`` is a stack-allocated object and it points to the first byte of 18450the object, the object is initially marked as dead. 18451``ptr`` is conservatively considered as a non-stack-allocated object if 18452the stack coloring algorithm that is used in the optimization pipeline cannot 18453conclude that ``ptr`` is a stack-allocated object. 18454 18455After '``llvm.lifetime.start``', the stack object that ``ptr`` points is marked 18456as alive and has an uninitialized value. 18457The stack object is marked as dead when either 18458:ref:`llvm.lifetime.end <int_lifeend>` to the alloca is executed or the 18459function returns. 18460 18461After :ref:`llvm.lifetime.end <int_lifeend>` is called, 18462'``llvm.lifetime.start``' on the stack object can be called again. 18463The second '``llvm.lifetime.start``' call marks the object as alive, but it 18464does not change the address of the object. 18465 18466If ``ptr`` is a non-stack-allocated object, it does not point to the first 18467byte of the object or it is a stack object that is already alive, it simply 18468fills all bytes of the object with ``poison``. 18469 18470 18471.. _int_lifeend: 18472 18473'``llvm.lifetime.end``' Intrinsic 18474^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18475 18476Syntax: 18477""""""" 18478 18479:: 18480 18481 declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>) 18482 18483Overview: 18484""""""""" 18485 18486The '``llvm.lifetime.end``' intrinsic specifies the end of a memory object's 18487lifetime. 18488 18489Arguments: 18490"""""""""" 18491 18492The first argument is a constant integer representing the size of the 18493object, or -1 if it is variable sized. The second argument is a pointer 18494to the object. 18495 18496Semantics: 18497"""""""""" 18498 18499If ``ptr`` is a stack-allocated object and it points to the first byte of the 18500object, the object is dead. 18501``ptr`` is conservatively considered as a non-stack-allocated object if 18502the stack coloring algorithm that is used in the optimization pipeline cannot 18503conclude that ``ptr`` is a stack-allocated object. 18504 18505Calling ``llvm.lifetime.end`` on an already dead alloca is no-op. 18506 18507If ``ptr`` is a non-stack-allocated object or it does not point to the first 18508byte of the object, it is equivalent to simply filling all bytes of the object 18509with ``poison``. 18510 18511 18512'``llvm.invariant.start``' Intrinsic 18513^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18514 18515Syntax: 18516""""""" 18517This is an overloaded intrinsic. The memory object can belong to any address space. 18518 18519:: 18520 18521 declare {}* @llvm.invariant.start.p0i8(i64 <size>, i8* nocapture <ptr>) 18522 18523Overview: 18524""""""""" 18525 18526The '``llvm.invariant.start``' intrinsic specifies that the contents of 18527a memory object will not change. 18528 18529Arguments: 18530"""""""""" 18531 18532The first argument is a constant integer representing the size of the 18533object, or -1 if it is variable sized. The second argument is a pointer 18534to the object. 18535 18536Semantics: 18537"""""""""" 18538 18539This intrinsic indicates that until an ``llvm.invariant.end`` that uses 18540the return value, the referenced memory location is constant and 18541unchanging. 18542 18543'``llvm.invariant.end``' Intrinsic 18544^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18545 18546Syntax: 18547""""""" 18548This is an overloaded intrinsic. The memory object can belong to any address space. 18549 18550:: 18551 18552 declare void @llvm.invariant.end.p0i8({}* <start>, i64 <size>, i8* nocapture <ptr>) 18553 18554Overview: 18555""""""""" 18556 18557The '``llvm.invariant.end``' intrinsic specifies that the contents of a 18558memory object are mutable. 18559 18560Arguments: 18561"""""""""" 18562 18563The first argument is the matching ``llvm.invariant.start`` intrinsic. 18564The second argument is a constant integer representing the size of the 18565object, or -1 if it is variable sized and the third argument is a 18566pointer to the object. 18567 18568Semantics: 18569"""""""""" 18570 18571This intrinsic indicates that the memory is mutable again. 18572 18573'``llvm.launder.invariant.group``' Intrinsic 18574^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18575 18576Syntax: 18577""""""" 18578This is an overloaded intrinsic. The memory object can belong to any address 18579space. The returned pointer must belong to the same address space as the 18580argument. 18581 18582:: 18583 18584 declare i8* @llvm.launder.invariant.group.p0i8(i8* <ptr>) 18585 18586Overview: 18587""""""""" 18588 18589The '``llvm.launder.invariant.group``' intrinsic can be used when an invariant 18590established by ``invariant.group`` metadata no longer holds, to obtain a new 18591pointer value that carries fresh invariant group information. It is an 18592experimental intrinsic, which means that its semantics might change in the 18593future. 18594 18595 18596Arguments: 18597"""""""""" 18598 18599The ``llvm.launder.invariant.group`` takes only one argument, which is a pointer 18600to the memory. 18601 18602Semantics: 18603"""""""""" 18604 18605Returns another pointer that aliases its argument but which is considered different 18606for the purposes of ``load``/``store`` ``invariant.group`` metadata. 18607It does not read any accessible memory and the execution can be speculated. 18608 18609'``llvm.strip.invariant.group``' Intrinsic 18610^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18611 18612Syntax: 18613""""""" 18614This is an overloaded intrinsic. The memory object can belong to any address 18615space. The returned pointer must belong to the same address space as the 18616argument. 18617 18618:: 18619 18620 declare i8* @llvm.strip.invariant.group.p0i8(i8* <ptr>) 18621 18622Overview: 18623""""""""" 18624 18625The '``llvm.strip.invariant.group``' intrinsic can be used when an invariant 18626established by ``invariant.group`` metadata no longer holds, to obtain a new pointer 18627value that does not carry the invariant information. It is an experimental 18628intrinsic, which means that its semantics might change in the future. 18629 18630 18631Arguments: 18632"""""""""" 18633 18634The ``llvm.strip.invariant.group`` takes only one argument, which is a pointer 18635to the memory. 18636 18637Semantics: 18638"""""""""" 18639 18640Returns another pointer that aliases its argument but which has no associated 18641``invariant.group`` metadata. 18642It does not read any memory and can be speculated. 18643 18644 18645 18646.. _constrainedfp: 18647 18648Constrained Floating-Point Intrinsics 18649------------------------------------- 18650 18651These intrinsics are used to provide special handling of floating-point 18652operations when specific rounding mode or floating-point exception behavior is 18653required. By default, LLVM optimization passes assume that the rounding mode is 18654round-to-nearest and that floating-point exceptions will not be monitored. 18655Constrained FP intrinsics are used to support non-default rounding modes and 18656accurately preserve exception behavior without compromising LLVM's ability to 18657optimize FP code when the default behavior is used. 18658 18659If any FP operation in a function is constrained then they all must be 18660constrained. This is required for correct LLVM IR. Optimizations that 18661move code around can create miscompiles if mixing of constrained and normal 18662operations is done. The correct way to mix constrained and less constrained 18663operations is to use the rounding mode and exception handling metadata to 18664mark constrained intrinsics as having LLVM's default behavior. 18665 18666Each of these intrinsics corresponds to a normal floating-point operation. The 18667data arguments and the return value are the same as the corresponding FP 18668operation. 18669 18670The rounding mode argument is a metadata string specifying what 18671assumptions, if any, the optimizer can make when transforming constant 18672values. Some constrained FP intrinsics omit this argument. If required 18673by the intrinsic, this argument must be one of the following strings: 18674 18675:: 18676 18677 "round.dynamic" 18678 "round.tonearest" 18679 "round.downward" 18680 "round.upward" 18681 "round.towardzero" 18682 "round.tonearestaway" 18683 18684If this argument is "round.dynamic" optimization passes must assume that the 18685rounding mode is unknown and may change at runtime. No transformations that 18686depend on rounding mode may be performed in this case. 18687 18688The other possible values for the rounding mode argument correspond to the 18689similarly named IEEE rounding modes. If the argument is any of these values 18690optimization passes may perform transformations as long as they are consistent 18691with the specified rounding mode. 18692 18693For example, 'x-0'->'x' is not a valid transformation if the rounding mode is 18694"round.downward" or "round.dynamic" because if the value of 'x' is +0 then 18695'x-0' should evaluate to '-0' when rounding downward. However, this 18696transformation is legal for all other rounding modes. 18697 18698For values other than "round.dynamic" optimization passes may assume that the 18699actual runtime rounding mode (as defined in a target-specific manner) matches 18700the specified rounding mode, but this is not guaranteed. Using a specific 18701non-dynamic rounding mode which does not match the actual rounding mode at 18702runtime results in undefined behavior. 18703 18704The exception behavior argument is a metadata string describing the floating 18705point exception semantics that required for the intrinsic. This argument 18706must be one of the following strings: 18707 18708:: 18709 18710 "fpexcept.ignore" 18711 "fpexcept.maytrap" 18712 "fpexcept.strict" 18713 18714If this argument is "fpexcept.ignore" optimization passes may assume that the 18715exception status flags will not be read and that floating-point exceptions will 18716be masked. This allows transformations to be performed that may change the 18717exception semantics of the original code. For example, FP operations may be 18718speculatively executed in this case whereas they must not be for either of the 18719other possible values of this argument. 18720 18721If the exception behavior argument is "fpexcept.maytrap" optimization passes 18722must avoid transformations that may raise exceptions that would not have been 18723raised by the original code (such as speculatively executing FP operations), but 18724passes are not required to preserve all exceptions that are implied by the 18725original code. For example, exceptions may be potentially hidden by constant 18726folding. 18727 18728If the exception behavior argument is "fpexcept.strict" all transformations must 18729strictly preserve the floating-point exception semantics of the original code. 18730Any FP exception that would have been raised by the original code must be raised 18731by the transformed code, and the transformed code must not raise any FP 18732exceptions that would not have been raised by the original code. This is the 18733exception behavior argument that will be used if the code being compiled reads 18734the FP exception status flags, but this mode can also be used with code that 18735unmasks FP exceptions. 18736 18737The number and order of floating-point exceptions is NOT guaranteed. For 18738example, a series of FP operations that each may raise exceptions may be 18739vectorized into a single instruction that raises each unique exception a single 18740time. 18741 18742Proper :ref:`function attributes <fnattrs>` usage is required for the 18743constrained intrinsics to function correctly. 18744 18745All function *calls* done in a function that uses constrained floating 18746point intrinsics must have the ``strictfp`` attribute. 18747 18748All function *definitions* that use constrained floating point intrinsics 18749must have the ``strictfp`` attribute. 18750 18751'``llvm.experimental.constrained.fadd``' Intrinsic 18752^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18753 18754Syntax: 18755""""""" 18756 18757:: 18758 18759 declare <type> 18760 @llvm.experimental.constrained.fadd(<type> <op1>, <type> <op2>, 18761 metadata <rounding mode>, 18762 metadata <exception behavior>) 18763 18764Overview: 18765""""""""" 18766 18767The '``llvm.experimental.constrained.fadd``' intrinsic returns the sum of its 18768two operands. 18769 18770 18771Arguments: 18772"""""""""" 18773 18774The first two arguments to the '``llvm.experimental.constrained.fadd``' 18775intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 18776of floating-point values. Both arguments must have identical types. 18777 18778The third and fourth arguments specify the rounding mode and exception 18779behavior as described above. 18780 18781Semantics: 18782"""""""""" 18783 18784The value produced is the floating-point sum of the two value operands and has 18785the same type as the operands. 18786 18787 18788'``llvm.experimental.constrained.fsub``' Intrinsic 18789^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18790 18791Syntax: 18792""""""" 18793 18794:: 18795 18796 declare <type> 18797 @llvm.experimental.constrained.fsub(<type> <op1>, <type> <op2>, 18798 metadata <rounding mode>, 18799 metadata <exception behavior>) 18800 18801Overview: 18802""""""""" 18803 18804The '``llvm.experimental.constrained.fsub``' intrinsic returns the difference 18805of its two operands. 18806 18807 18808Arguments: 18809"""""""""" 18810 18811The first two arguments to the '``llvm.experimental.constrained.fsub``' 18812intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 18813of floating-point values. Both arguments must have identical types. 18814 18815The third and fourth arguments specify the rounding mode and exception 18816behavior as described above. 18817 18818Semantics: 18819"""""""""" 18820 18821The value produced is the floating-point difference of the two value operands 18822and has the same type as the operands. 18823 18824 18825'``llvm.experimental.constrained.fmul``' Intrinsic 18826^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18827 18828Syntax: 18829""""""" 18830 18831:: 18832 18833 declare <type> 18834 @llvm.experimental.constrained.fmul(<type> <op1>, <type> <op2>, 18835 metadata <rounding mode>, 18836 metadata <exception behavior>) 18837 18838Overview: 18839""""""""" 18840 18841The '``llvm.experimental.constrained.fmul``' intrinsic returns the product of 18842its two operands. 18843 18844 18845Arguments: 18846"""""""""" 18847 18848The first two arguments to the '``llvm.experimental.constrained.fmul``' 18849intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 18850of floating-point values. Both arguments must have identical types. 18851 18852The third and fourth arguments specify the rounding mode and exception 18853behavior as described above. 18854 18855Semantics: 18856"""""""""" 18857 18858The value produced is the floating-point product of the two value operands and 18859has the same type as the operands. 18860 18861 18862'``llvm.experimental.constrained.fdiv``' Intrinsic 18863^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18864 18865Syntax: 18866""""""" 18867 18868:: 18869 18870 declare <type> 18871 @llvm.experimental.constrained.fdiv(<type> <op1>, <type> <op2>, 18872 metadata <rounding mode>, 18873 metadata <exception behavior>) 18874 18875Overview: 18876""""""""" 18877 18878The '``llvm.experimental.constrained.fdiv``' intrinsic returns the quotient of 18879its two operands. 18880 18881 18882Arguments: 18883"""""""""" 18884 18885The first two arguments to the '``llvm.experimental.constrained.fdiv``' 18886intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 18887of floating-point values. Both arguments must have identical types. 18888 18889The third and fourth arguments specify the rounding mode and exception 18890behavior as described above. 18891 18892Semantics: 18893"""""""""" 18894 18895The value produced is the floating-point quotient of the two value operands and 18896has the same type as the operands. 18897 18898 18899'``llvm.experimental.constrained.frem``' Intrinsic 18900^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18901 18902Syntax: 18903""""""" 18904 18905:: 18906 18907 declare <type> 18908 @llvm.experimental.constrained.frem(<type> <op1>, <type> <op2>, 18909 metadata <rounding mode>, 18910 metadata <exception behavior>) 18911 18912Overview: 18913""""""""" 18914 18915The '``llvm.experimental.constrained.frem``' intrinsic returns the remainder 18916from the division of its two operands. 18917 18918 18919Arguments: 18920"""""""""" 18921 18922The first two arguments to the '``llvm.experimental.constrained.frem``' 18923intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 18924of floating-point values. Both arguments must have identical types. 18925 18926The third and fourth arguments specify the rounding mode and exception 18927behavior as described above. The rounding mode argument has no effect, since 18928the result of frem is never rounded, but the argument is included for 18929consistency with the other constrained floating-point intrinsics. 18930 18931Semantics: 18932"""""""""" 18933 18934The value produced is the floating-point remainder from the division of the two 18935value operands and has the same type as the operands. The remainder has the 18936same sign as the dividend. 18937 18938'``llvm.experimental.constrained.fma``' Intrinsic 18939^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18940 18941Syntax: 18942""""""" 18943 18944:: 18945 18946 declare <type> 18947 @llvm.experimental.constrained.fma(<type> <op1>, <type> <op2>, <type> <op3>, 18948 metadata <rounding mode>, 18949 metadata <exception behavior>) 18950 18951Overview: 18952""""""""" 18953 18954The '``llvm.experimental.constrained.fma``' intrinsic returns the result of a 18955fused-multiply-add operation on its operands. 18956 18957Arguments: 18958"""""""""" 18959 18960The first three arguments to the '``llvm.experimental.constrained.fma``' 18961intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector 18962<t_vector>` of floating-point values. All arguments must have identical types. 18963 18964The fourth and fifth arguments specify the rounding mode and exception behavior 18965as described above. 18966 18967Semantics: 18968"""""""""" 18969 18970The result produced is the product of the first two operands added to the third 18971operand computed with infinite precision, and then rounded to the target 18972precision. 18973 18974'``llvm.experimental.constrained.fptoui``' Intrinsic 18975^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18976 18977Syntax: 18978""""""" 18979 18980:: 18981 18982 declare <ty2> 18983 @llvm.experimental.constrained.fptoui(<type> <value>, 18984 metadata <exception behavior>) 18985 18986Overview: 18987""""""""" 18988 18989The '``llvm.experimental.constrained.fptoui``' intrinsic converts a 18990floating-point ``value`` to its unsigned integer equivalent of type ``ty2``. 18991 18992Arguments: 18993"""""""""" 18994 18995The first argument to the '``llvm.experimental.constrained.fptoui``' 18996intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 18997<t_vector>` of floating point values. 18998 18999The second argument specifies the exception behavior as described above. 19000 19001Semantics: 19002"""""""""" 19003 19004The result produced is an unsigned integer converted from the floating 19005point operand. The value is truncated, so it is rounded towards zero. 19006 19007'``llvm.experimental.constrained.fptosi``' Intrinsic 19008^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19009 19010Syntax: 19011""""""" 19012 19013:: 19014 19015 declare <ty2> 19016 @llvm.experimental.constrained.fptosi(<type> <value>, 19017 metadata <exception behavior>) 19018 19019Overview: 19020""""""""" 19021 19022The '``llvm.experimental.constrained.fptosi``' intrinsic converts 19023:ref:`floating-point <t_floating>` ``value`` to type ``ty2``. 19024 19025Arguments: 19026"""""""""" 19027 19028The first argument to the '``llvm.experimental.constrained.fptosi``' 19029intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 19030<t_vector>` of floating point values. 19031 19032The second argument specifies the exception behavior as described above. 19033 19034Semantics: 19035"""""""""" 19036 19037The result produced is a signed integer converted from the floating 19038point operand. The value is truncated, so it is rounded towards zero. 19039 19040'``llvm.experimental.constrained.uitofp``' Intrinsic 19041^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19042 19043Syntax: 19044""""""" 19045 19046:: 19047 19048 declare <ty2> 19049 @llvm.experimental.constrained.uitofp(<type> <value>, 19050 metadata <rounding mode>, 19051 metadata <exception behavior>) 19052 19053Overview: 19054""""""""" 19055 19056The '``llvm.experimental.constrained.uitofp``' intrinsic converts an 19057unsigned integer ``value`` to a floating-point of type ``ty2``. 19058 19059Arguments: 19060"""""""""" 19061 19062The first argument to the '``llvm.experimental.constrained.uitofp``' 19063intrinsic must be an :ref:`integer <t_integer>` or :ref:`vector 19064<t_vector>` of integer values. 19065 19066The second and third arguments specify the rounding mode and exception 19067behavior as described above. 19068 19069Semantics: 19070"""""""""" 19071 19072An inexact floating-point exception will be raised if rounding is required. 19073Any result produced is a floating point value converted from the input 19074integer operand. 19075 19076'``llvm.experimental.constrained.sitofp``' Intrinsic 19077^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19078 19079Syntax: 19080""""""" 19081 19082:: 19083 19084 declare <ty2> 19085 @llvm.experimental.constrained.sitofp(<type> <value>, 19086 metadata <rounding mode>, 19087 metadata <exception behavior>) 19088 19089Overview: 19090""""""""" 19091 19092The '``llvm.experimental.constrained.sitofp``' intrinsic converts a 19093signed integer ``value`` to a floating-point of type ``ty2``. 19094 19095Arguments: 19096"""""""""" 19097 19098The first argument to the '``llvm.experimental.constrained.sitofp``' 19099intrinsic must be an :ref:`integer <t_integer>` or :ref:`vector 19100<t_vector>` of integer values. 19101 19102The second and third arguments specify the rounding mode and exception 19103behavior as described above. 19104 19105Semantics: 19106"""""""""" 19107 19108An inexact floating-point exception will be raised if rounding is required. 19109Any result produced is a floating point value converted from the input 19110integer operand. 19111 19112'``llvm.experimental.constrained.fptrunc``' Intrinsic 19113^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19114 19115Syntax: 19116""""""" 19117 19118:: 19119 19120 declare <ty2> 19121 @llvm.experimental.constrained.fptrunc(<type> <value>, 19122 metadata <rounding mode>, 19123 metadata <exception behavior>) 19124 19125Overview: 19126""""""""" 19127 19128The '``llvm.experimental.constrained.fptrunc``' intrinsic truncates ``value`` 19129to type ``ty2``. 19130 19131Arguments: 19132"""""""""" 19133 19134The first argument to the '``llvm.experimental.constrained.fptrunc``' 19135intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 19136<t_vector>` of floating point values. This argument must be larger in size 19137than the result. 19138 19139The second and third arguments specify the rounding mode and exception 19140behavior as described above. 19141 19142Semantics: 19143"""""""""" 19144 19145The result produced is a floating point value truncated to be smaller in size 19146than the operand. 19147 19148'``llvm.experimental.constrained.fpext``' Intrinsic 19149^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19150 19151Syntax: 19152""""""" 19153 19154:: 19155 19156 declare <ty2> 19157 @llvm.experimental.constrained.fpext(<type> <value>, 19158 metadata <exception behavior>) 19159 19160Overview: 19161""""""""" 19162 19163The '``llvm.experimental.constrained.fpext``' intrinsic extends a 19164floating-point ``value`` to a larger floating-point value. 19165 19166Arguments: 19167"""""""""" 19168 19169The first argument to the '``llvm.experimental.constrained.fpext``' 19170intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 19171<t_vector>` of floating point values. This argument must be smaller in size 19172than the result. 19173 19174The second argument specifies the exception behavior as described above. 19175 19176Semantics: 19177"""""""""" 19178 19179The result produced is a floating point value extended to be larger in size 19180than the operand. All restrictions that apply to the fpext instruction also 19181apply to this intrinsic. 19182 19183'``llvm.experimental.constrained.fcmp``' and '``llvm.experimental.constrained.fcmps``' Intrinsics 19184^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19185 19186Syntax: 19187""""""" 19188 19189:: 19190 19191 declare <ty2> 19192 @llvm.experimental.constrained.fcmp(<type> <op1>, <type> <op2>, 19193 metadata <condition code>, 19194 metadata <exception behavior>) 19195 declare <ty2> 19196 @llvm.experimental.constrained.fcmps(<type> <op1>, <type> <op2>, 19197 metadata <condition code>, 19198 metadata <exception behavior>) 19199 19200Overview: 19201""""""""" 19202 19203The '``llvm.experimental.constrained.fcmp``' and 19204'``llvm.experimental.constrained.fcmps``' intrinsics return a boolean 19205value or vector of boolean values based on comparison of its operands. 19206 19207If the operands are floating-point scalars, then the result type is a 19208boolean (:ref:`i1 <t_integer>`). 19209 19210If the operands are floating-point vectors, then the result type is a 19211vector of boolean with the same number of elements as the operands being 19212compared. 19213 19214The '``llvm.experimental.constrained.fcmp``' intrinsic performs a quiet 19215comparison operation while the '``llvm.experimental.constrained.fcmps``' 19216intrinsic performs a signaling comparison operation. 19217 19218Arguments: 19219"""""""""" 19220 19221The first two arguments to the '``llvm.experimental.constrained.fcmp``' 19222and '``llvm.experimental.constrained.fcmps``' intrinsics must be 19223:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 19224of floating-point values. Both arguments must have identical types. 19225 19226The third argument is the condition code indicating the kind of comparison 19227to perform. It must be a metadata string with one of the following values: 19228 19229- "``oeq``": ordered and equal 19230- "``ogt``": ordered and greater than 19231- "``oge``": ordered and greater than or equal 19232- "``olt``": ordered and less than 19233- "``ole``": ordered and less than or equal 19234- "``one``": ordered and not equal 19235- "``ord``": ordered (no nans) 19236- "``ueq``": unordered or equal 19237- "``ugt``": unordered or greater than 19238- "``uge``": unordered or greater than or equal 19239- "``ult``": unordered or less than 19240- "``ule``": unordered or less than or equal 19241- "``une``": unordered or not equal 19242- "``uno``": unordered (either nans) 19243 19244*Ordered* means that neither operand is a NAN while *unordered* means 19245that either operand may be a NAN. 19246 19247The fourth argument specifies the exception behavior as described above. 19248 19249Semantics: 19250"""""""""" 19251 19252``op1`` and ``op2`` are compared according to the condition code given 19253as the third argument. If the operands are vectors, then the 19254vectors are compared element by element. Each comparison performed 19255always yields an :ref:`i1 <t_integer>` result, as follows: 19256 19257- "``oeq``": yields ``true`` if both operands are not a NAN and ``op1`` 19258 is equal to ``op2``. 19259- "``ogt``": yields ``true`` if both operands are not a NAN and ``op1`` 19260 is greater than ``op2``. 19261- "``oge``": yields ``true`` if both operands are not a NAN and ``op1`` 19262 is greater than or equal to ``op2``. 19263- "``olt``": yields ``true`` if both operands are not a NAN and ``op1`` 19264 is less than ``op2``. 19265- "``ole``": yields ``true`` if both operands are not a NAN and ``op1`` 19266 is less than or equal to ``op2``. 19267- "``one``": yields ``true`` if both operands are not a NAN and ``op1`` 19268 is not equal to ``op2``. 19269- "``ord``": yields ``true`` if both operands are not a NAN. 19270- "``ueq``": yields ``true`` if either operand is a NAN or ``op1`` is 19271 equal to ``op2``. 19272- "``ugt``": yields ``true`` if either operand is a NAN or ``op1`` is 19273 greater than ``op2``. 19274- "``uge``": yields ``true`` if either operand is a NAN or ``op1`` is 19275 greater than or equal to ``op2``. 19276- "``ult``": yields ``true`` if either operand is a NAN or ``op1`` is 19277 less than ``op2``. 19278- "``ule``": yields ``true`` if either operand is a NAN or ``op1`` is 19279 less than or equal to ``op2``. 19280- "``une``": yields ``true`` if either operand is a NAN or ``op1`` is 19281 not equal to ``op2``. 19282- "``uno``": yields ``true`` if either operand is a NAN. 19283 19284The quiet comparison operation performed by 19285'``llvm.experimental.constrained.fcmp``' will only raise an exception 19286if either operand is a SNAN. The signaling comparison operation 19287performed by '``llvm.experimental.constrained.fcmps``' will raise an 19288exception if either operand is a NAN (QNAN or SNAN). Such an exception 19289does not preclude a result being produced (e.g. exception might only 19290set a flag), therefore the distinction between ordered and unordered 19291comparisons is also relevant for the 19292'``llvm.experimental.constrained.fcmps``' intrinsic. 19293 19294'``llvm.experimental.constrained.fmuladd``' Intrinsic 19295^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19296 19297Syntax: 19298""""""" 19299 19300:: 19301 19302 declare <type> 19303 @llvm.experimental.constrained.fmuladd(<type> <op1>, <type> <op2>, 19304 <type> <op3>, 19305 metadata <rounding mode>, 19306 metadata <exception behavior>) 19307 19308Overview: 19309""""""""" 19310 19311The '``llvm.experimental.constrained.fmuladd``' intrinsic represents 19312multiply-add expressions that can be fused if the code generator determines 19313that (a) the target instruction set has support for a fused operation, 19314and (b) that the fused operation is more efficient than the equivalent, 19315separate pair of mul and add instructions. 19316 19317Arguments: 19318"""""""""" 19319 19320The first three arguments to the '``llvm.experimental.constrained.fmuladd``' 19321intrinsic must be floating-point or vector of floating-point values. 19322All three arguments must have identical types. 19323 19324The fourth and fifth arguments specify the rounding mode and exception behavior 19325as described above. 19326 19327Semantics: 19328"""""""""" 19329 19330The expression: 19331 19332:: 19333 19334 %0 = call float @llvm.experimental.constrained.fmuladd.f32(%a, %b, %c, 19335 metadata <rounding mode>, 19336 metadata <exception behavior>) 19337 19338is equivalent to the expression: 19339 19340:: 19341 19342 %0 = call float @llvm.experimental.constrained.fmul.f32(%a, %b, 19343 metadata <rounding mode>, 19344 metadata <exception behavior>) 19345 %1 = call float @llvm.experimental.constrained.fadd.f32(%0, %c, 19346 metadata <rounding mode>, 19347 metadata <exception behavior>) 19348 19349except that it is unspecified whether rounding will be performed between the 19350multiplication and addition steps. Fusion is not guaranteed, even if the target 19351platform supports it. 19352If a fused multiply-add is required, the corresponding 19353:ref:`llvm.experimental.constrained.fma <int_fma>` intrinsic function should be 19354used instead. 19355This never sets errno, just as '``llvm.experimental.constrained.fma.*``'. 19356 19357Constrained libm-equivalent Intrinsics 19358-------------------------------------- 19359 19360In addition to the basic floating-point operations for which constrained 19361intrinsics are described above, there are constrained versions of various 19362operations which provide equivalent behavior to a corresponding libm function. 19363These intrinsics allow the precise behavior of these operations with respect to 19364rounding mode and exception behavior to be controlled. 19365 19366As with the basic constrained floating-point intrinsics, the rounding mode 19367and exception behavior arguments only control the behavior of the optimizer. 19368They do not change the runtime floating-point environment. 19369 19370 19371'``llvm.experimental.constrained.sqrt``' Intrinsic 19372^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19373 19374Syntax: 19375""""""" 19376 19377:: 19378 19379 declare <type> 19380 @llvm.experimental.constrained.sqrt(<type> <op1>, 19381 metadata <rounding mode>, 19382 metadata <exception behavior>) 19383 19384Overview: 19385""""""""" 19386 19387The '``llvm.experimental.constrained.sqrt``' intrinsic returns the square root 19388of the specified value, returning the same value as the libm '``sqrt``' 19389functions would, but without setting ``errno``. 19390 19391Arguments: 19392"""""""""" 19393 19394The first argument and the return type are floating-point numbers of the same 19395type. 19396 19397The second and third arguments specify the rounding mode and exception 19398behavior as described above. 19399 19400Semantics: 19401"""""""""" 19402 19403This function returns the nonnegative square root of the specified value. 19404If the value is less than negative zero, a floating-point exception occurs 19405and the return value is architecture specific. 19406 19407 19408'``llvm.experimental.constrained.pow``' Intrinsic 19409^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19410 19411Syntax: 19412""""""" 19413 19414:: 19415 19416 declare <type> 19417 @llvm.experimental.constrained.pow(<type> <op1>, <type> <op2>, 19418 metadata <rounding mode>, 19419 metadata <exception behavior>) 19420 19421Overview: 19422""""""""" 19423 19424The '``llvm.experimental.constrained.pow``' intrinsic returns the first operand 19425raised to the (positive or negative) power specified by the second operand. 19426 19427Arguments: 19428"""""""""" 19429 19430The first two arguments and the return value are floating-point numbers of the 19431same type. The second argument specifies the power to which the first argument 19432should be raised. 19433 19434The third and fourth arguments specify the rounding mode and exception 19435behavior as described above. 19436 19437Semantics: 19438"""""""""" 19439 19440This function returns the first value raised to the second power, 19441returning the same values as the libm ``pow`` functions would, and 19442handles error conditions in the same way. 19443 19444 19445'``llvm.experimental.constrained.powi``' Intrinsic 19446^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19447 19448Syntax: 19449""""""" 19450 19451:: 19452 19453 declare <type> 19454 @llvm.experimental.constrained.powi(<type> <op1>, i32 <op2>, 19455 metadata <rounding mode>, 19456 metadata <exception behavior>) 19457 19458Overview: 19459""""""""" 19460 19461The '``llvm.experimental.constrained.powi``' intrinsic returns the first operand 19462raised to the (positive or negative) power specified by the second operand. The 19463order of evaluation of multiplications is not defined. When a vector of 19464floating-point type is used, the second argument remains a scalar integer value. 19465 19466 19467Arguments: 19468"""""""""" 19469 19470The first argument and the return value are floating-point numbers of the same 19471type. The second argument is a 32-bit signed integer specifying the power to 19472which the first argument should be raised. 19473 19474The third and fourth arguments specify the rounding mode and exception 19475behavior as described above. 19476 19477Semantics: 19478"""""""""" 19479 19480This function returns the first value raised to the second power with an 19481unspecified sequence of rounding operations. 19482 19483 19484'``llvm.experimental.constrained.sin``' Intrinsic 19485^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19486 19487Syntax: 19488""""""" 19489 19490:: 19491 19492 declare <type> 19493 @llvm.experimental.constrained.sin(<type> <op1>, 19494 metadata <rounding mode>, 19495 metadata <exception behavior>) 19496 19497Overview: 19498""""""""" 19499 19500The '``llvm.experimental.constrained.sin``' intrinsic returns the sine of the 19501first operand. 19502 19503Arguments: 19504"""""""""" 19505 19506The first argument and the return type are floating-point numbers of the same 19507type. 19508 19509The second and third arguments specify the rounding mode and exception 19510behavior as described above. 19511 19512Semantics: 19513"""""""""" 19514 19515This function returns the sine of the specified operand, returning the 19516same values as the libm ``sin`` functions would, and handles error 19517conditions in the same way. 19518 19519 19520'``llvm.experimental.constrained.cos``' Intrinsic 19521^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19522 19523Syntax: 19524""""""" 19525 19526:: 19527 19528 declare <type> 19529 @llvm.experimental.constrained.cos(<type> <op1>, 19530 metadata <rounding mode>, 19531 metadata <exception behavior>) 19532 19533Overview: 19534""""""""" 19535 19536The '``llvm.experimental.constrained.cos``' intrinsic returns the cosine of the 19537first operand. 19538 19539Arguments: 19540"""""""""" 19541 19542The first argument and the return type are floating-point numbers of the same 19543type. 19544 19545The second and third arguments specify the rounding mode and exception 19546behavior as described above. 19547 19548Semantics: 19549"""""""""" 19550 19551This function returns the cosine of the specified operand, returning the 19552same values as the libm ``cos`` functions would, and handles error 19553conditions in the same way. 19554 19555 19556'``llvm.experimental.constrained.exp``' Intrinsic 19557^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19558 19559Syntax: 19560""""""" 19561 19562:: 19563 19564 declare <type> 19565 @llvm.experimental.constrained.exp(<type> <op1>, 19566 metadata <rounding mode>, 19567 metadata <exception behavior>) 19568 19569Overview: 19570""""""""" 19571 19572The '``llvm.experimental.constrained.exp``' intrinsic computes the base-e 19573exponential of the specified value. 19574 19575Arguments: 19576"""""""""" 19577 19578The first argument and the return value are floating-point numbers of the same 19579type. 19580 19581The second and third arguments specify the rounding mode and exception 19582behavior as described above. 19583 19584Semantics: 19585"""""""""" 19586 19587This function returns the same values as the libm ``exp`` functions 19588would, and handles error conditions in the same way. 19589 19590 19591'``llvm.experimental.constrained.exp2``' Intrinsic 19592^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19593 19594Syntax: 19595""""""" 19596 19597:: 19598 19599 declare <type> 19600 @llvm.experimental.constrained.exp2(<type> <op1>, 19601 metadata <rounding mode>, 19602 metadata <exception behavior>) 19603 19604Overview: 19605""""""""" 19606 19607The '``llvm.experimental.constrained.exp2``' intrinsic computes the base-2 19608exponential of the specified value. 19609 19610 19611Arguments: 19612"""""""""" 19613 19614The first argument and the return value are floating-point numbers of the same 19615type. 19616 19617The second and third arguments specify the rounding mode and exception 19618behavior as described above. 19619 19620Semantics: 19621"""""""""" 19622 19623This function returns the same values as the libm ``exp2`` functions 19624would, and handles error conditions in the same way. 19625 19626 19627'``llvm.experimental.constrained.log``' Intrinsic 19628^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19629 19630Syntax: 19631""""""" 19632 19633:: 19634 19635 declare <type> 19636 @llvm.experimental.constrained.log(<type> <op1>, 19637 metadata <rounding mode>, 19638 metadata <exception behavior>) 19639 19640Overview: 19641""""""""" 19642 19643The '``llvm.experimental.constrained.log``' intrinsic computes the base-e 19644logarithm of the specified value. 19645 19646Arguments: 19647"""""""""" 19648 19649The first argument and the return value are floating-point numbers of the same 19650type. 19651 19652The second and third arguments specify the rounding mode and exception 19653behavior as described above. 19654 19655 19656Semantics: 19657"""""""""" 19658 19659This function returns the same values as the libm ``log`` functions 19660would, and handles error conditions in the same way. 19661 19662 19663'``llvm.experimental.constrained.log10``' Intrinsic 19664^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19665 19666Syntax: 19667""""""" 19668 19669:: 19670 19671 declare <type> 19672 @llvm.experimental.constrained.log10(<type> <op1>, 19673 metadata <rounding mode>, 19674 metadata <exception behavior>) 19675 19676Overview: 19677""""""""" 19678 19679The '``llvm.experimental.constrained.log10``' intrinsic computes the base-10 19680logarithm of the specified value. 19681 19682Arguments: 19683"""""""""" 19684 19685The first argument and the return value are floating-point numbers of the same 19686type. 19687 19688The second and third arguments specify the rounding mode and exception 19689behavior as described above. 19690 19691Semantics: 19692"""""""""" 19693 19694This function returns the same values as the libm ``log10`` functions 19695would, and handles error conditions in the same way. 19696 19697 19698'``llvm.experimental.constrained.log2``' Intrinsic 19699^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19700 19701Syntax: 19702""""""" 19703 19704:: 19705 19706 declare <type> 19707 @llvm.experimental.constrained.log2(<type> <op1>, 19708 metadata <rounding mode>, 19709 metadata <exception behavior>) 19710 19711Overview: 19712""""""""" 19713 19714The '``llvm.experimental.constrained.log2``' intrinsic computes the base-2 19715logarithm of the specified value. 19716 19717Arguments: 19718"""""""""" 19719 19720The first argument and the return value are floating-point numbers of the same 19721type. 19722 19723The second and third arguments specify the rounding mode and exception 19724behavior as described above. 19725 19726Semantics: 19727"""""""""" 19728 19729This function returns the same values as the libm ``log2`` functions 19730would, and handles error conditions in the same way. 19731 19732 19733'``llvm.experimental.constrained.rint``' Intrinsic 19734^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19735 19736Syntax: 19737""""""" 19738 19739:: 19740 19741 declare <type> 19742 @llvm.experimental.constrained.rint(<type> <op1>, 19743 metadata <rounding mode>, 19744 metadata <exception behavior>) 19745 19746Overview: 19747""""""""" 19748 19749The '``llvm.experimental.constrained.rint``' intrinsic returns the first 19750operand rounded to the nearest integer. It may raise an inexact floating-point 19751exception if the operand is not an integer. 19752 19753Arguments: 19754"""""""""" 19755 19756The first argument and the return value are floating-point numbers of the same 19757type. 19758 19759The second and third arguments specify the rounding mode and exception 19760behavior as described above. 19761 19762Semantics: 19763"""""""""" 19764 19765This function returns the same values as the libm ``rint`` functions 19766would, and handles error conditions in the same way. The rounding mode is 19767described, not determined, by the rounding mode argument. The actual rounding 19768mode is determined by the runtime floating-point environment. The rounding 19769mode argument is only intended as information to the compiler. 19770 19771 19772'``llvm.experimental.constrained.lrint``' Intrinsic 19773^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19774 19775Syntax: 19776""""""" 19777 19778:: 19779 19780 declare <inttype> 19781 @llvm.experimental.constrained.lrint(<fptype> <op1>, 19782 metadata <rounding mode>, 19783 metadata <exception behavior>) 19784 19785Overview: 19786""""""""" 19787 19788The '``llvm.experimental.constrained.lrint``' intrinsic returns the first 19789operand rounded to the nearest integer. An inexact floating-point exception 19790will be raised if the operand is not an integer. An invalid exception is 19791raised if the result is too large to fit into a supported integer type, 19792and in this case the result is undefined. 19793 19794Arguments: 19795"""""""""" 19796 19797The first argument is a floating-point number. The return value is an 19798integer type. Not all types are supported on all targets. The supported 19799types are the same as the ``llvm.lrint`` intrinsic and the ``lrint`` 19800libm functions. 19801 19802The second and third arguments specify the rounding mode and exception 19803behavior as described above. 19804 19805Semantics: 19806"""""""""" 19807 19808This function returns the same values as the libm ``lrint`` functions 19809would, and handles error conditions in the same way. 19810 19811The rounding mode is described, not determined, by the rounding mode 19812argument. The actual rounding mode is determined by the runtime floating-point 19813environment. The rounding mode argument is only intended as information 19814to the compiler. 19815 19816If the runtime floating-point environment is using the default rounding mode 19817then the results will be the same as the llvm.lrint intrinsic. 19818 19819 19820'``llvm.experimental.constrained.llrint``' Intrinsic 19821^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19822 19823Syntax: 19824""""""" 19825 19826:: 19827 19828 declare <inttype> 19829 @llvm.experimental.constrained.llrint(<fptype> <op1>, 19830 metadata <rounding mode>, 19831 metadata <exception behavior>) 19832 19833Overview: 19834""""""""" 19835 19836The '``llvm.experimental.constrained.llrint``' intrinsic returns the first 19837operand rounded to the nearest integer. An inexact floating-point exception 19838will be raised if the operand is not an integer. An invalid exception is 19839raised if the result is too large to fit into a supported integer type, 19840and in this case the result is undefined. 19841 19842Arguments: 19843"""""""""" 19844 19845The first argument is a floating-point number. The return value is an 19846integer type. Not all types are supported on all targets. The supported 19847types are the same as the ``llvm.llrint`` intrinsic and the ``llrint`` 19848libm functions. 19849 19850The second and third arguments specify the rounding mode and exception 19851behavior as described above. 19852 19853Semantics: 19854"""""""""" 19855 19856This function returns the same values as the libm ``llrint`` functions 19857would, and handles error conditions in the same way. 19858 19859The rounding mode is described, not determined, by the rounding mode 19860argument. The actual rounding mode is determined by the runtime floating-point 19861environment. The rounding mode argument is only intended as information 19862to the compiler. 19863 19864If the runtime floating-point environment is using the default rounding mode 19865then the results will be the same as the llvm.llrint intrinsic. 19866 19867 19868'``llvm.experimental.constrained.nearbyint``' Intrinsic 19869^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19870 19871Syntax: 19872""""""" 19873 19874:: 19875 19876 declare <type> 19877 @llvm.experimental.constrained.nearbyint(<type> <op1>, 19878 metadata <rounding mode>, 19879 metadata <exception behavior>) 19880 19881Overview: 19882""""""""" 19883 19884The '``llvm.experimental.constrained.nearbyint``' intrinsic returns the first 19885operand rounded to the nearest integer. It will not raise an inexact 19886floating-point exception if the operand is not an integer. 19887 19888 19889Arguments: 19890"""""""""" 19891 19892The first argument and the return value are floating-point numbers of the same 19893type. 19894 19895The second and third arguments specify the rounding mode and exception 19896behavior as described above. 19897 19898Semantics: 19899"""""""""" 19900 19901This function returns the same values as the libm ``nearbyint`` functions 19902would, and handles error conditions in the same way. The rounding mode is 19903described, not determined, by the rounding mode argument. The actual rounding 19904mode is determined by the runtime floating-point environment. The rounding 19905mode argument is only intended as information to the compiler. 19906 19907 19908'``llvm.experimental.constrained.maxnum``' Intrinsic 19909^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19910 19911Syntax: 19912""""""" 19913 19914:: 19915 19916 declare <type> 19917 @llvm.experimental.constrained.maxnum(<type> <op1>, <type> <op2> 19918 metadata <exception behavior>) 19919 19920Overview: 19921""""""""" 19922 19923The '``llvm.experimental.constrained.maxnum``' intrinsic returns the maximum 19924of the two arguments. 19925 19926Arguments: 19927"""""""""" 19928 19929The first two arguments and the return value are floating-point numbers 19930of the same type. 19931 19932The third argument specifies the exception behavior as described above. 19933 19934Semantics: 19935"""""""""" 19936 19937This function follows the IEEE-754 semantics for maxNum. 19938 19939 19940'``llvm.experimental.constrained.minnum``' Intrinsic 19941^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19942 19943Syntax: 19944""""""" 19945 19946:: 19947 19948 declare <type> 19949 @llvm.experimental.constrained.minnum(<type> <op1>, <type> <op2> 19950 metadata <exception behavior>) 19951 19952Overview: 19953""""""""" 19954 19955The '``llvm.experimental.constrained.minnum``' intrinsic returns the minimum 19956of the two arguments. 19957 19958Arguments: 19959"""""""""" 19960 19961The first two arguments and the return value are floating-point numbers 19962of the same type. 19963 19964The third argument specifies the exception behavior as described above. 19965 19966Semantics: 19967"""""""""" 19968 19969This function follows the IEEE-754 semantics for minNum. 19970 19971 19972'``llvm.experimental.constrained.maximum``' Intrinsic 19973^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19974 19975Syntax: 19976""""""" 19977 19978:: 19979 19980 declare <type> 19981 @llvm.experimental.constrained.maximum(<type> <op1>, <type> <op2> 19982 metadata <exception behavior>) 19983 19984Overview: 19985""""""""" 19986 19987The '``llvm.experimental.constrained.maximum``' intrinsic returns the maximum 19988of the two arguments, propagating NaNs and treating -0.0 as less than +0.0. 19989 19990Arguments: 19991"""""""""" 19992 19993The first two arguments and the return value are floating-point numbers 19994of the same type. 19995 19996The third argument specifies the exception behavior as described above. 19997 19998Semantics: 19999"""""""""" 20000 20001This function follows semantics specified in the draft of IEEE 754-2018. 20002 20003 20004'``llvm.experimental.constrained.minimum``' Intrinsic 20005^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20006 20007Syntax: 20008""""""" 20009 20010:: 20011 20012 declare <type> 20013 @llvm.experimental.constrained.minimum(<type> <op1>, <type> <op2> 20014 metadata <exception behavior>) 20015 20016Overview: 20017""""""""" 20018 20019The '``llvm.experimental.constrained.minimum``' intrinsic returns the minimum 20020of the two arguments, propagating NaNs and treating -0.0 as less than +0.0. 20021 20022Arguments: 20023"""""""""" 20024 20025The first two arguments and the return value are floating-point numbers 20026of the same type. 20027 20028The third argument specifies the exception behavior as described above. 20029 20030Semantics: 20031"""""""""" 20032 20033This function follows semantics specified in the draft of IEEE 754-2018. 20034 20035 20036'``llvm.experimental.constrained.ceil``' Intrinsic 20037^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20038 20039Syntax: 20040""""""" 20041 20042:: 20043 20044 declare <type> 20045 @llvm.experimental.constrained.ceil(<type> <op1>, 20046 metadata <exception behavior>) 20047 20048Overview: 20049""""""""" 20050 20051The '``llvm.experimental.constrained.ceil``' intrinsic returns the ceiling of the 20052first operand. 20053 20054Arguments: 20055"""""""""" 20056 20057The first argument and the return value are floating-point numbers of the same 20058type. 20059 20060The second argument specifies the exception behavior as described above. 20061 20062Semantics: 20063"""""""""" 20064 20065This function returns the same values as the libm ``ceil`` functions 20066would and handles error conditions in the same way. 20067 20068 20069'``llvm.experimental.constrained.floor``' Intrinsic 20070^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20071 20072Syntax: 20073""""""" 20074 20075:: 20076 20077 declare <type> 20078 @llvm.experimental.constrained.floor(<type> <op1>, 20079 metadata <exception behavior>) 20080 20081Overview: 20082""""""""" 20083 20084The '``llvm.experimental.constrained.floor``' intrinsic returns the floor of the 20085first operand. 20086 20087Arguments: 20088"""""""""" 20089 20090The first argument and the return value are floating-point numbers of the same 20091type. 20092 20093The second argument specifies the exception behavior as described above. 20094 20095Semantics: 20096"""""""""" 20097 20098This function returns the same values as the libm ``floor`` functions 20099would and handles error conditions in the same way. 20100 20101 20102'``llvm.experimental.constrained.round``' Intrinsic 20103^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20104 20105Syntax: 20106""""""" 20107 20108:: 20109 20110 declare <type> 20111 @llvm.experimental.constrained.round(<type> <op1>, 20112 metadata <exception behavior>) 20113 20114Overview: 20115""""""""" 20116 20117The '``llvm.experimental.constrained.round``' intrinsic returns the first 20118operand rounded to the nearest integer. 20119 20120Arguments: 20121"""""""""" 20122 20123The first argument and the return value are floating-point numbers of the same 20124type. 20125 20126The second argument specifies the exception behavior as described above. 20127 20128Semantics: 20129"""""""""" 20130 20131This function returns the same values as the libm ``round`` functions 20132would and handles error conditions in the same way. 20133 20134 20135'``llvm.experimental.constrained.roundeven``' Intrinsic 20136^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20137 20138Syntax: 20139""""""" 20140 20141:: 20142 20143 declare <type> 20144 @llvm.experimental.constrained.roundeven(<type> <op1>, 20145 metadata <exception behavior>) 20146 20147Overview: 20148""""""""" 20149 20150The '``llvm.experimental.constrained.roundeven``' intrinsic returns the first 20151operand rounded to the nearest integer in floating-point format, rounding 20152halfway cases to even (that is, to the nearest value that is an even integer), 20153regardless of the current rounding direction. 20154 20155Arguments: 20156"""""""""" 20157 20158The first argument and the return value are floating-point numbers of the same 20159type. 20160 20161The second argument specifies the exception behavior as described above. 20162 20163Semantics: 20164"""""""""" 20165 20166This function implements IEEE-754 operation ``roundToIntegralTiesToEven``. It 20167also behaves in the same way as C standard function ``roundeven`` and can signal 20168the invalid operation exception for a SNAN operand. 20169 20170 20171'``llvm.experimental.constrained.lround``' Intrinsic 20172^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20173 20174Syntax: 20175""""""" 20176 20177:: 20178 20179 declare <inttype> 20180 @llvm.experimental.constrained.lround(<fptype> <op1>, 20181 metadata <exception behavior>) 20182 20183Overview: 20184""""""""" 20185 20186The '``llvm.experimental.constrained.lround``' intrinsic returns the first 20187operand rounded to the nearest integer with ties away from zero. It will 20188raise an inexact floating-point exception if the operand is not an integer. 20189An invalid exception is raised if the result is too large to fit into a 20190supported integer type, and in this case the result is undefined. 20191 20192Arguments: 20193"""""""""" 20194 20195The first argument is a floating-point number. The return value is an 20196integer type. Not all types are supported on all targets. The supported 20197types are the same as the ``llvm.lround`` intrinsic and the ``lround`` 20198libm functions. 20199 20200The second argument specifies the exception behavior as described above. 20201 20202Semantics: 20203"""""""""" 20204 20205This function returns the same values as the libm ``lround`` functions 20206would and handles error conditions in the same way. 20207 20208 20209'``llvm.experimental.constrained.llround``' Intrinsic 20210^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20211 20212Syntax: 20213""""""" 20214 20215:: 20216 20217 declare <inttype> 20218 @llvm.experimental.constrained.llround(<fptype> <op1>, 20219 metadata <exception behavior>) 20220 20221Overview: 20222""""""""" 20223 20224The '``llvm.experimental.constrained.llround``' intrinsic returns the first 20225operand rounded to the nearest integer with ties away from zero. It will 20226raise an inexact floating-point exception if the operand is not an integer. 20227An invalid exception is raised if the result is too large to fit into a 20228supported integer type, and in this case the result is undefined. 20229 20230Arguments: 20231"""""""""" 20232 20233The first argument is a floating-point number. The return value is an 20234integer type. Not all types are supported on all targets. The supported 20235types are the same as the ``llvm.llround`` intrinsic and the ``llround`` 20236libm functions. 20237 20238The second argument specifies the exception behavior as described above. 20239 20240Semantics: 20241"""""""""" 20242 20243This function returns the same values as the libm ``llround`` functions 20244would and handles error conditions in the same way. 20245 20246 20247'``llvm.experimental.constrained.trunc``' Intrinsic 20248^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20249 20250Syntax: 20251""""""" 20252 20253:: 20254 20255 declare <type> 20256 @llvm.experimental.constrained.trunc(<type> <op1>, 20257 metadata <exception behavior>) 20258 20259Overview: 20260""""""""" 20261 20262The '``llvm.experimental.constrained.trunc``' intrinsic returns the first 20263operand rounded to the nearest integer not larger in magnitude than the 20264operand. 20265 20266Arguments: 20267"""""""""" 20268 20269The first argument and the return value are floating-point numbers of the same 20270type. 20271 20272The second argument specifies the exception behavior as described above. 20273 20274Semantics: 20275"""""""""" 20276 20277This function returns the same values as the libm ``trunc`` functions 20278would and handles error conditions in the same way. 20279 20280.. _int_experimental_noalias_scope_decl: 20281 20282'``llvm.experimental.noalias.scope.decl``' Intrinsic 20283^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20284 20285Syntax: 20286""""""" 20287 20288 20289:: 20290 20291 declare void @llvm.experimental.noalias.scope.decl(metadata !id.scope.list) 20292 20293Overview: 20294""""""""" 20295 20296The ``llvm.experimental.noalias.scope.decl`` intrinsic identifies where a 20297noalias scope is declared. When the intrinsic is duplicated, a decision must 20298also be made about the scope: depending on the reason of the duplication, 20299the scope might need to be duplicated as well. 20300 20301 20302Arguments: 20303"""""""""" 20304 20305The ``!id.scope.list`` argument is metadata that is a list of ``noalias`` 20306metadata references. The format is identical to that required for ``noalias`` 20307metadata. This list must have exactly one element. 20308 20309Semantics: 20310"""""""""" 20311 20312The ``llvm.experimental.noalias.scope.decl`` intrinsic identifies where a 20313noalias scope is declared. When the intrinsic is duplicated, a decision must 20314also be made about the scope: depending on the reason of the duplication, 20315the scope might need to be duplicated as well. 20316 20317For example, when the intrinsic is used inside a loop body, and that loop is 20318unrolled, the associated noalias scope must also be duplicated. Otherwise, the 20319noalias property it signifies would spill across loop iterations, whereas it 20320was only valid within a single iteration. 20321 20322.. code-block:: llvm 20323 20324 ; This examples shows two possible positions for noalias.decl and how they impact the semantics: 20325 ; If it is outside the loop (Version 1), then %a and %b are noalias across *all* iterations. 20326 ; If it is inside the loop (Version 2), then %a and %b are noalias only within *one* iteration. 20327 declare void @decl_in_loop(i8* %a.base, i8* %b.base) { 20328 entry: 20329 ; call void @llvm.experimental.noalias.scope.decl(metadata !2) ; Version 1: noalias decl outside loop 20330 br label %loop 20331 20332 loop: 20333 %a = phi i8* [ %a.base, %entry ], [ %a.inc, %loop ] 20334 %b = phi i8* [ %b.base, %entry ], [ %b.inc, %loop ] 20335 ; call void @llvm.experimental.noalias.scope.decl(metadata !2) ; Version 2: noalias decl inside loop 20336 %val = load i8, i8* %a, !alias.scope !2 20337 store i8 %val, i8* %b, !noalias !2 20338 %a.inc = getelementptr inbounds i8, i8* %a, i64 1 20339 %b.inc = getelementptr inbounds i8, i8* %b, i64 1 20340 %cond = call i1 @cond() 20341 br i1 %cond, label %loop, label %exit 20342 20343 exit: 20344 ret void 20345 } 20346 20347 !0 = !{!0} ; domain 20348 !1 = !{!1, !0} ; scope 20349 !2 = !{!1} ; scope list 20350 20351Multiple calls to `@llvm.experimental.noalias.scope.decl` for the same scope 20352are possible, but one should never dominate another. Violations are pointed out 20353by the verifier as they indicate a problem in either a transformation pass or 20354the input. 20355 20356 20357Floating Point Environment Manipulation intrinsics 20358-------------------------------------------------- 20359 20360These functions read or write floating point environment, such as rounding 20361mode or state of floating point exceptions. Altering the floating point 20362environment requires special care. See :ref:`Floating Point Environment <floatenv>`. 20363 20364'``llvm.flt.rounds``' Intrinsic 20365^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20366 20367Syntax: 20368""""""" 20369 20370:: 20371 20372 declare i32 @llvm.flt.rounds() 20373 20374Overview: 20375""""""""" 20376 20377The '``llvm.flt.rounds``' intrinsic reads the current rounding mode. 20378 20379Semantics: 20380"""""""""" 20381 20382The '``llvm.flt.rounds``' intrinsic returns the current rounding mode. 20383Encoding of the returned values is same as the result of ``FLT_ROUNDS``, 20384specified by C standard: 20385 20386:: 20387 20388 0 - toward zero 20389 1 - to nearest, ties to even 20390 2 - toward positive infinity 20391 3 - toward negative infinity 20392 4 - to nearest, ties away from zero 20393 20394Other values may be used to represent additional rounding modes, supported by a 20395target. These values are target-specific. 20396 20397 20398'``llvm.set.rounding``' Intrinsic 20399^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20400 20401Syntax: 20402""""""" 20403 20404:: 20405 20406 declare void @llvm.set.rounding(i32 <val>) 20407 20408Overview: 20409""""""""" 20410 20411The '``llvm.set.rounding``' intrinsic sets current rounding mode. 20412 20413Arguments: 20414"""""""""" 20415 20416The argument is the required rounding mode. Encoding of rounding mode is 20417the same as used by '``llvm.flt.rounds``'. 20418 20419Semantics: 20420"""""""""" 20421 20422The '``llvm.set.rounding``' intrinsic sets the current rounding mode. It is 20423similar to C library function 'fesetround', however this intrinsic does not 20424return any value and uses platform-independent representation of IEEE rounding 20425modes. 20426 20427 20428General Intrinsics 20429------------------ 20430 20431This class of intrinsics is designed to be generic and has no specific 20432purpose. 20433 20434'``llvm.var.annotation``' Intrinsic 20435^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20436 20437Syntax: 20438""""""" 20439 20440:: 20441 20442 declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>) 20443 20444Overview: 20445""""""""" 20446 20447The '``llvm.var.annotation``' intrinsic. 20448 20449Arguments: 20450"""""""""" 20451 20452The first argument is a pointer to a value, the second is a pointer to a 20453global string, the third is a pointer to a global string which is the 20454source file name, and the last argument is the line number. 20455 20456Semantics: 20457"""""""""" 20458 20459This intrinsic allows annotation of local variables with arbitrary 20460strings. This can be useful for special purpose optimizations that want 20461to look for these annotations. These have no other defined use; they are 20462ignored by code generation and optimization. 20463 20464'``llvm.ptr.annotation.*``' Intrinsic 20465^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20466 20467Syntax: 20468""""""" 20469 20470This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a 20471pointer to an integer of any width. *NOTE* you must specify an address space for 20472the pointer. The identifier for the default address space is the integer 20473'``0``'. 20474 20475:: 20476 20477 declare i8* @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32 <int>) 20478 declare i16* @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32 <int>) 20479 declare i32* @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32 <int>) 20480 declare i64* @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32 <int>) 20481 declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32 <int>) 20482 20483Overview: 20484""""""""" 20485 20486The '``llvm.ptr.annotation``' intrinsic. 20487 20488Arguments: 20489"""""""""" 20490 20491The first argument is a pointer to an integer value of arbitrary bitwidth 20492(result of some expression), the second is a pointer to a global string, the 20493third is a pointer to a global string which is the source file name, and the 20494last argument is the line number. It returns the value of the first argument. 20495 20496Semantics: 20497"""""""""" 20498 20499This intrinsic allows annotation of a pointer to an integer with arbitrary 20500strings. This can be useful for special purpose optimizations that want to look 20501for these annotations. These have no other defined use; they are ignored by code 20502generation and optimization. 20503 20504'``llvm.annotation.*``' Intrinsic 20505^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20506 20507Syntax: 20508""""""" 20509 20510This is an overloaded intrinsic. You can use '``llvm.annotation``' on 20511any integer bit width. 20512 20513:: 20514 20515 declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>) 20516 declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>) 20517 declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>) 20518 declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>) 20519 declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>) 20520 20521Overview: 20522""""""""" 20523 20524The '``llvm.annotation``' intrinsic. 20525 20526Arguments: 20527"""""""""" 20528 20529The first argument is an integer value (result of some expression), the 20530second is a pointer to a global string, the third is a pointer to a 20531global string which is the source file name, and the last argument is 20532the line number. It returns the value of the first argument. 20533 20534Semantics: 20535"""""""""" 20536 20537This intrinsic allows annotations to be put on arbitrary expressions 20538with arbitrary strings. This can be useful for special purpose 20539optimizations that want to look for these annotations. These have no 20540other defined use; they are ignored by code generation and optimization. 20541 20542'``llvm.codeview.annotation``' Intrinsic 20543^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20544 20545Syntax: 20546""""""" 20547 20548This annotation emits a label at its program point and an associated 20549``S_ANNOTATION`` codeview record with some additional string metadata. This is 20550used to implement MSVC's ``__annotation`` intrinsic. It is marked 20551``noduplicate``, so calls to this intrinsic prevent inlining and should be 20552considered expensive. 20553 20554:: 20555 20556 declare void @llvm.codeview.annotation(metadata) 20557 20558Arguments: 20559"""""""""" 20560 20561The argument should be an MDTuple containing any number of MDStrings. 20562 20563'``llvm.trap``' Intrinsic 20564^^^^^^^^^^^^^^^^^^^^^^^^^ 20565 20566Syntax: 20567""""""" 20568 20569:: 20570 20571 declare void @llvm.trap() cold noreturn nounwind 20572 20573Overview: 20574""""""""" 20575 20576The '``llvm.trap``' intrinsic. 20577 20578Arguments: 20579"""""""""" 20580 20581None. 20582 20583Semantics: 20584"""""""""" 20585 20586This intrinsic is lowered to the target dependent trap instruction. If 20587the target does not have a trap instruction, this intrinsic will be 20588lowered to a call of the ``abort()`` function. 20589 20590'``llvm.debugtrap``' Intrinsic 20591^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20592 20593Syntax: 20594""""""" 20595 20596:: 20597 20598 declare void @llvm.debugtrap() nounwind 20599 20600Overview: 20601""""""""" 20602 20603The '``llvm.debugtrap``' intrinsic. 20604 20605Arguments: 20606"""""""""" 20607 20608None. 20609 20610Semantics: 20611"""""""""" 20612 20613This intrinsic is lowered to code which is intended to cause an 20614execution trap with the intention of requesting the attention of a 20615debugger. 20616 20617'``llvm.ubsantrap``' Intrinsic 20618^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20619 20620Syntax: 20621""""""" 20622 20623:: 20624 20625 declare void @llvm.ubsantrap(i8 immarg) cold noreturn nounwind 20626 20627Overview: 20628""""""""" 20629 20630The '``llvm.ubsantrap``' intrinsic. 20631 20632Arguments: 20633"""""""""" 20634 20635An integer describing the kind of failure detected. 20636 20637Semantics: 20638"""""""""" 20639 20640This intrinsic is lowered to code which is intended to cause an execution trap, 20641embedding the argument into encoding of that trap somehow to discriminate 20642crashes if possible. 20643 20644Equivalent to ``@llvm.trap`` for targets that do not support this behaviour. 20645 20646'``llvm.stackprotector``' Intrinsic 20647^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20648 20649Syntax: 20650""""""" 20651 20652:: 20653 20654 declare void @llvm.stackprotector(i8* <guard>, i8** <slot>) 20655 20656Overview: 20657""""""""" 20658 20659The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it 20660onto the stack at ``slot``. The stack slot is adjusted to ensure that it 20661is placed on the stack before local variables. 20662 20663Arguments: 20664"""""""""" 20665 20666The ``llvm.stackprotector`` intrinsic requires two pointer arguments. 20667The first argument is the value loaded from the stack guard 20668``@__stack_chk_guard``. The second variable is an ``alloca`` that has 20669enough space to hold the value of the guard. 20670 20671Semantics: 20672"""""""""" 20673 20674This intrinsic causes the prologue/epilogue inserter to force the position of 20675the ``AllocaInst`` stack slot to be before local variables on the stack. This is 20676to ensure that if a local variable on the stack is overwritten, it will destroy 20677the value of the guard. When the function exits, the guard on the stack is 20678checked against the original guard by ``llvm.stackprotectorcheck``. If they are 20679different, then ``llvm.stackprotectorcheck`` causes the program to abort by 20680calling the ``__stack_chk_fail()`` function. 20681 20682'``llvm.stackguard``' Intrinsic 20683^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20684 20685Syntax: 20686""""""" 20687 20688:: 20689 20690 declare i8* @llvm.stackguard() 20691 20692Overview: 20693""""""""" 20694 20695The ``llvm.stackguard`` intrinsic returns the system stack guard value. 20696 20697It should not be generated by frontends, since it is only for internal usage. 20698The reason why we create this intrinsic is that we still support IR form Stack 20699Protector in FastISel. 20700 20701Arguments: 20702"""""""""" 20703 20704None. 20705 20706Semantics: 20707"""""""""" 20708 20709On some platforms, the value returned by this intrinsic remains unchanged 20710between loads in the same thread. On other platforms, it returns the same 20711global variable value, if any, e.g. ``@__stack_chk_guard``. 20712 20713Currently some platforms have IR-level customized stack guard loading (e.g. 20714X86 Linux) that is not handled by ``llvm.stackguard()``, while they should be 20715in the future. 20716 20717'``llvm.objectsize``' Intrinsic 20718^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20719 20720Syntax: 20721""""""" 20722 20723:: 20724 20725 declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>) 20726 declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>) 20727 20728Overview: 20729""""""""" 20730 20731The ``llvm.objectsize`` intrinsic is designed to provide information to the 20732optimizer to determine whether a) an operation (like memcpy) will overflow a 20733buffer that corresponds to an object, or b) that a runtime check for overflow 20734isn't necessary. An object in this context means an allocation of a specific 20735class, structure, array, or other object. 20736 20737Arguments: 20738"""""""""" 20739 20740The ``llvm.objectsize`` intrinsic takes four arguments. The first argument is a 20741pointer to or into the ``object``. The second argument determines whether 20742``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size is 20743unknown. The third argument controls how ``llvm.objectsize`` acts when ``null`` 20744in address space 0 is used as its pointer argument. If it's ``false``, 20745``llvm.objectsize`` reports 0 bytes available when given ``null``. Otherwise, if 20746the ``null`` is in a non-zero address space or if ``true`` is given for the 20747third argument of ``llvm.objectsize``, we assume its size is unknown. The fourth 20748argument to ``llvm.objectsize`` determines if the value should be evaluated at 20749runtime. 20750 20751The second, third, and fourth arguments only accept constants. 20752 20753Semantics: 20754"""""""""" 20755 20756The ``llvm.objectsize`` intrinsic is lowered to a value representing the size of 20757the object concerned. If the size cannot be determined, ``llvm.objectsize`` 20758returns ``i32/i64 -1 or 0`` (depending on the ``min`` argument). 20759 20760'``llvm.expect``' Intrinsic 20761^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20762 20763Syntax: 20764""""""" 20765 20766This is an overloaded intrinsic. You can use ``llvm.expect`` on any 20767integer bit width. 20768 20769:: 20770 20771 declare i1 @llvm.expect.i1(i1 <val>, i1 <expected_val>) 20772 declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>) 20773 declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>) 20774 20775Overview: 20776""""""""" 20777 20778The ``llvm.expect`` intrinsic provides information about expected (the 20779most probable) value of ``val``, which can be used by optimizers. 20780 20781Arguments: 20782"""""""""" 20783 20784The ``llvm.expect`` intrinsic takes two arguments. The first argument is 20785a value. The second argument is an expected value. 20786 20787Semantics: 20788"""""""""" 20789 20790This intrinsic is lowered to the ``val``. 20791 20792'``llvm.expect.with.probability``' Intrinsic 20793^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20794 20795Syntax: 20796""""""" 20797 20798This intrinsic is similar to ``llvm.expect``. This is an overloaded intrinsic. 20799You can use ``llvm.expect.with.probability`` on any integer bit width. 20800 20801:: 20802 20803 declare i1 @llvm.expect.with.probability.i1(i1 <val>, i1 <expected_val>, double <prob>) 20804 declare i32 @llvm.expect.with.probability.i32(i32 <val>, i32 <expected_val>, double <prob>) 20805 declare i64 @llvm.expect.with.probability.i64(i64 <val>, i64 <expected_val>, double <prob>) 20806 20807Overview: 20808""""""""" 20809 20810The ``llvm.expect.with.probability`` intrinsic provides information about 20811expected value of ``val`` with probability(or confidence) ``prob``, which can 20812be used by optimizers. 20813 20814Arguments: 20815"""""""""" 20816 20817The ``llvm.expect.with.probability`` intrinsic takes three arguments. The first 20818argument is a value. The second argument is an expected value. The third 20819argument is a probability. 20820 20821Semantics: 20822"""""""""" 20823 20824This intrinsic is lowered to the ``val``. 20825 20826.. _int_assume: 20827 20828'``llvm.assume``' Intrinsic 20829^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20830 20831Syntax: 20832""""""" 20833 20834:: 20835 20836 declare void @llvm.assume(i1 %cond) 20837 20838Overview: 20839""""""""" 20840 20841The ``llvm.assume`` allows the optimizer to assume that the provided 20842condition is true. This information can then be used in simplifying other parts 20843of the code. 20844 20845More complex assumptions can be encoded as 20846:ref:`assume operand bundles <assume_opbundles>`. 20847 20848Arguments: 20849"""""""""" 20850 20851The argument of the call is the condition which the optimizer may assume is 20852always true. 20853 20854Semantics: 20855"""""""""" 20856 20857The intrinsic allows the optimizer to assume that the provided condition is 20858always true whenever the control flow reaches the intrinsic call. No code is 20859generated for this intrinsic, and instructions that contribute only to the 20860provided condition are not used for code generation. If the condition is 20861violated during execution, the behavior is undefined. 20862 20863Note that the optimizer might limit the transformations performed on values 20864used by the ``llvm.assume`` intrinsic in order to preserve the instructions 20865only used to form the intrinsic's input argument. This might prove undesirable 20866if the extra information provided by the ``llvm.assume`` intrinsic does not cause 20867sufficient overall improvement in code quality. For this reason, 20868``llvm.assume`` should not be used to document basic mathematical invariants 20869that the optimizer can otherwise deduce or facts that are of little use to the 20870optimizer. 20871 20872.. _int_ssa_copy: 20873 20874'``llvm.ssa.copy``' Intrinsic 20875^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20876 20877Syntax: 20878""""""" 20879 20880:: 20881 20882 declare type @llvm.ssa.copy(type %operand) returned(1) readnone 20883 20884Arguments: 20885"""""""""" 20886 20887The first argument is an operand which is used as the returned value. 20888 20889Overview: 20890"""""""""" 20891 20892The ``llvm.ssa.copy`` intrinsic can be used to attach information to 20893operations by copying them and giving them new names. For example, 20894the PredicateInfo utility uses it to build Extended SSA form, and 20895attach various forms of information to operands that dominate specific 20896uses. It is not meant for general use, only for building temporary 20897renaming forms that require value splits at certain points. 20898 20899.. _type.test: 20900 20901'``llvm.type.test``' Intrinsic 20902^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20903 20904Syntax: 20905""""""" 20906 20907:: 20908 20909 declare i1 @llvm.type.test(i8* %ptr, metadata %type) nounwind readnone 20910 20911 20912Arguments: 20913"""""""""" 20914 20915The first argument is a pointer to be tested. The second argument is a 20916metadata object representing a :doc:`type identifier <TypeMetadata>`. 20917 20918Overview: 20919""""""""" 20920 20921The ``llvm.type.test`` intrinsic tests whether the given pointer is associated 20922with the given type identifier. 20923 20924.. _type.checked.load: 20925 20926'``llvm.type.checked.load``' Intrinsic 20927^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20928 20929Syntax: 20930""""""" 20931 20932:: 20933 20934 declare {i8*, i1} @llvm.type.checked.load(i8* %ptr, i32 %offset, metadata %type) argmemonly nounwind readonly 20935 20936 20937Arguments: 20938"""""""""" 20939 20940The first argument is a pointer from which to load a function pointer. The 20941second argument is the byte offset from which to load the function pointer. The 20942third argument is a metadata object representing a :doc:`type identifier 20943<TypeMetadata>`. 20944 20945Overview: 20946""""""""" 20947 20948The ``llvm.type.checked.load`` intrinsic safely loads a function pointer from a 20949virtual table pointer using type metadata. This intrinsic is used to implement 20950control flow integrity in conjunction with virtual call optimization. The 20951virtual call optimization pass will optimize away ``llvm.type.checked.load`` 20952intrinsics associated with devirtualized calls, thereby removing the type 20953check in cases where it is not needed to enforce the control flow integrity 20954constraint. 20955 20956If the given pointer is associated with a type metadata identifier, this 20957function returns true as the second element of its return value. (Note that 20958the function may also return true if the given pointer is not associated 20959with a type metadata identifier.) If the function's return value's second 20960element is true, the following rules apply to the first element: 20961 20962- If the given pointer is associated with the given type metadata identifier, 20963 it is the function pointer loaded from the given byte offset from the given 20964 pointer. 20965 20966- If the given pointer is not associated with the given type metadata 20967 identifier, it is one of the following (the choice of which is unspecified): 20968 20969 1. The function pointer that would have been loaded from an arbitrarily chosen 20970 (through an unspecified mechanism) pointer associated with the type 20971 metadata. 20972 20973 2. If the function has a non-void return type, a pointer to a function that 20974 returns an unspecified value without causing side effects. 20975 20976If the function's return value's second element is false, the value of the 20977first element is undefined. 20978 20979 20980'``llvm.donothing``' Intrinsic 20981^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20982 20983Syntax: 20984""""""" 20985 20986:: 20987 20988 declare void @llvm.donothing() nounwind readnone 20989 20990Overview: 20991""""""""" 20992 20993The ``llvm.donothing`` intrinsic doesn't perform any operation. It's one of only 20994three intrinsics (besides ``llvm.experimental.patchpoint`` and 20995``llvm.experimental.gc.statepoint``) that can be called with an invoke 20996instruction. 20997 20998Arguments: 20999"""""""""" 21000 21001None. 21002 21003Semantics: 21004"""""""""" 21005 21006This intrinsic does nothing, and it's removed by optimizers and ignored 21007by codegen. 21008 21009'``llvm.experimental.deoptimize``' Intrinsic 21010^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21011 21012Syntax: 21013""""""" 21014 21015:: 21016 21017 declare type @llvm.experimental.deoptimize(...) [ "deopt"(...) ] 21018 21019Overview: 21020""""""""" 21021 21022This intrinsic, together with :ref:`deoptimization operand bundles 21023<deopt_opbundles>`, allow frontends to express transfer of control and 21024frame-local state from the currently executing (typically more specialized, 21025hence faster) version of a function into another (typically more generic, hence 21026slower) version. 21027 21028In languages with a fully integrated managed runtime like Java and JavaScript 21029this intrinsic can be used to implement "uncommon trap" or "side exit" like 21030functionality. In unmanaged languages like C and C++, this intrinsic can be 21031used to represent the slow paths of specialized functions. 21032 21033 21034Arguments: 21035"""""""""" 21036 21037The intrinsic takes an arbitrary number of arguments, whose meaning is 21038decided by the :ref:`lowering strategy<deoptimize_lowering>`. 21039 21040Semantics: 21041"""""""""" 21042 21043The ``@llvm.experimental.deoptimize`` intrinsic executes an attached 21044deoptimization continuation (denoted using a :ref:`deoptimization 21045operand bundle <deopt_opbundles>`) and returns the value returned by 21046the deoptimization continuation. Defining the semantic properties of 21047the continuation itself is out of scope of the language reference -- 21048as far as LLVM is concerned, the deoptimization continuation can 21049invoke arbitrary side effects, including reading from and writing to 21050the entire heap. 21051 21052Deoptimization continuations expressed using ``"deopt"`` operand bundles always 21053continue execution to the end of the physical frame containing them, so all 21054calls to ``@llvm.experimental.deoptimize`` must be in "tail position": 21055 21056 - ``@llvm.experimental.deoptimize`` cannot be invoked. 21057 - The call must immediately precede a :ref:`ret <i_ret>` instruction. 21058 - The ``ret`` instruction must return the value produced by the 21059 ``@llvm.experimental.deoptimize`` call if there is one, or void. 21060 21061Note that the above restrictions imply that the return type for a call to 21062``@llvm.experimental.deoptimize`` will match the return type of its immediate 21063caller. 21064 21065The inliner composes the ``"deopt"`` continuations of the caller into the 21066``"deopt"`` continuations present in the inlinee, and also updates calls to this 21067intrinsic to return directly from the frame of the function it inlined into. 21068 21069All declarations of ``@llvm.experimental.deoptimize`` must share the 21070same calling convention. 21071 21072.. _deoptimize_lowering: 21073 21074Lowering: 21075""""""""" 21076 21077Calls to ``@llvm.experimental.deoptimize`` are lowered to calls to the 21078symbol ``__llvm_deoptimize`` (it is the frontend's responsibility to 21079ensure that this symbol is defined). The call arguments to 21080``@llvm.experimental.deoptimize`` are lowered as if they were formal 21081arguments of the specified types, and not as varargs. 21082 21083 21084'``llvm.experimental.guard``' Intrinsic 21085^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21086 21087Syntax: 21088""""""" 21089 21090:: 21091 21092 declare void @llvm.experimental.guard(i1, ...) [ "deopt"(...) ] 21093 21094Overview: 21095""""""""" 21096 21097This intrinsic, together with :ref:`deoptimization operand bundles 21098<deopt_opbundles>`, allows frontends to express guards or checks on 21099optimistic assumptions made during compilation. The semantics of 21100``@llvm.experimental.guard`` is defined in terms of 21101``@llvm.experimental.deoptimize`` -- its body is defined to be 21102equivalent to: 21103 21104.. code-block:: text 21105 21106 define void @llvm.experimental.guard(i1 %pred, <args...>) { 21107 %realPred = and i1 %pred, undef 21108 br i1 %realPred, label %continue, label %leave [, !make.implicit !{}] 21109 21110 leave: 21111 call void @llvm.experimental.deoptimize(<args...>) [ "deopt"() ] 21112 ret void 21113 21114 continue: 21115 ret void 21116 } 21117 21118 21119with the optional ``[, !make.implicit !{}]`` present if and only if it 21120is present on the call site. For more details on ``!make.implicit``, 21121see :doc:`FaultMaps`. 21122 21123In words, ``@llvm.experimental.guard`` executes the attached 21124``"deopt"`` continuation if (but **not** only if) its first argument 21125is ``false``. Since the optimizer is allowed to replace the ``undef`` 21126with an arbitrary value, it can optimize guard to fail "spuriously", 21127i.e. without the original condition being false (hence the "not only 21128if"); and this allows for "check widening" type optimizations. 21129 21130``@llvm.experimental.guard`` cannot be invoked. 21131 21132After ``@llvm.experimental.guard`` was first added, a more general 21133formulation was found in ``@llvm.experimental.widenable.condition``. 21134Support for ``@llvm.experimental.guard`` is slowly being rephrased in 21135terms of this alternate. 21136 21137'``llvm.experimental.widenable.condition``' Intrinsic 21138^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21139 21140Syntax: 21141""""""" 21142 21143:: 21144 21145 declare i1 @llvm.experimental.widenable.condition() 21146 21147Overview: 21148""""""""" 21149 21150This intrinsic represents a "widenable condition" which is 21151boolean expressions with the following property: whether this 21152expression is `true` or `false`, the program is correct and 21153well-defined. 21154 21155Together with :ref:`deoptimization operand bundles <deopt_opbundles>`, 21156``@llvm.experimental.widenable.condition`` allows frontends to 21157express guards or checks on optimistic assumptions made during 21158compilation and represent them as branch instructions on special 21159conditions. 21160 21161While this may appear similar in semantics to `undef`, it is very 21162different in that an invocation produces a particular, singular 21163value. It is also intended to be lowered late, and remain available 21164for specific optimizations and transforms that can benefit from its 21165special properties. 21166 21167Arguments: 21168"""""""""" 21169 21170None. 21171 21172Semantics: 21173"""""""""" 21174 21175The intrinsic ``@llvm.experimental.widenable.condition()`` 21176returns either `true` or `false`. For each evaluation of a call 21177to this intrinsic, the program must be valid and correct both if 21178it returns `true` and if it returns `false`. This allows 21179transformation passes to replace evaluations of this intrinsic 21180with either value whenever one is beneficial. 21181 21182When used in a branch condition, it allows us to choose between 21183two alternative correct solutions for the same problem, like 21184in example below: 21185 21186.. code-block:: text 21187 21188 %cond = call i1 @llvm.experimental.widenable.condition() 21189 br i1 %cond, label %solution_1, label %solution_2 21190 21191 label %fast_path: 21192 ; Apply memory-consuming but fast solution for a task. 21193 21194 label %slow_path: 21195 ; Cheap in memory but slow solution. 21196 21197Whether the result of intrinsic's call is `true` or `false`, 21198it should be correct to pick either solution. We can switch 21199between them by replacing the result of 21200``@llvm.experimental.widenable.condition`` with different 21201`i1` expressions. 21202 21203This is how it can be used to represent guards as widenable branches: 21204 21205.. code-block:: text 21206 21207 block: 21208 ; Unguarded instructions 21209 call void @llvm.experimental.guard(i1 %cond, <args...>) ["deopt"(<deopt_args...>)] 21210 ; Guarded instructions 21211 21212Can be expressed in an alternative equivalent form of explicit branch using 21213``@llvm.experimental.widenable.condition``: 21214 21215.. code-block:: text 21216 21217 block: 21218 ; Unguarded instructions 21219 %widenable_condition = call i1 @llvm.experimental.widenable.condition() 21220 %guard_condition = and i1 %cond, %widenable_condition 21221 br i1 %guard_condition, label %guarded, label %deopt 21222 21223 guarded: 21224 ; Guarded instructions 21225 21226 deopt: 21227 call type @llvm.experimental.deoptimize(<args...>) [ "deopt"(<deopt_args...>) ] 21228 21229So the block `guarded` is only reachable when `%cond` is `true`, 21230and it should be valid to go to the block `deopt` whenever `%cond` 21231is `true` or `false`. 21232 21233``@llvm.experimental.widenable.condition`` will never throw, thus 21234it cannot be invoked. 21235 21236Guard widening: 21237""""""""""""""" 21238 21239When ``@llvm.experimental.widenable.condition()`` is used in 21240condition of a guard represented as explicit branch, it is 21241legal to widen the guard's condition with any additional 21242conditions. 21243 21244Guard widening looks like replacement of 21245 21246.. code-block:: text 21247 21248 %widenable_cond = call i1 @llvm.experimental.widenable.condition() 21249 %guard_cond = and i1 %cond, %widenable_cond 21250 br i1 %guard_cond, label %guarded, label %deopt 21251 21252with 21253 21254.. code-block:: text 21255 21256 %widenable_cond = call i1 @llvm.experimental.widenable.condition() 21257 %new_cond = and i1 %any_other_cond, %widenable_cond 21258 %new_guard_cond = and i1 %cond, %new_cond 21259 br i1 %new_guard_cond, label %guarded, label %deopt 21260 21261for this branch. Here `%any_other_cond` is an arbitrarily chosen 21262well-defined `i1` value. By making guard widening, we may 21263impose stricter conditions on `guarded` block and bail to the 21264deopt when the new condition is not met. 21265 21266Lowering: 21267""""""""" 21268 21269Default lowering strategy is replacing the result of 21270call of ``@llvm.experimental.widenable.condition`` with 21271constant `true`. However it is always correct to replace 21272it with any other `i1` value. Any pass can 21273freely do it if it can benefit from non-default lowering. 21274 21275 21276'``llvm.load.relative``' Intrinsic 21277^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21278 21279Syntax: 21280""""""" 21281 21282:: 21283 21284 declare i8* @llvm.load.relative.iN(i8* %ptr, iN %offset) argmemonly nounwind readonly 21285 21286Overview: 21287""""""""" 21288 21289This intrinsic loads a 32-bit value from the address ``%ptr + %offset``, 21290adds ``%ptr`` to that value and returns it. The constant folder specifically 21291recognizes the form of this intrinsic and the constant initializers it may 21292load from; if a loaded constant initializer is known to have the form 21293``i32 trunc(x - %ptr)``, the intrinsic call is folded to ``x``. 21294 21295LLVM provides that the calculation of such a constant initializer will 21296not overflow at link time under the medium code model if ``x`` is an 21297``unnamed_addr`` function. However, it does not provide this guarantee for 21298a constant initializer folded into a function body. This intrinsic can be 21299used to avoid the possibility of overflows when loading from such a constant. 21300 21301.. _llvm_sideeffect: 21302 21303'``llvm.sideeffect``' Intrinsic 21304^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21305 21306Syntax: 21307""""""" 21308 21309:: 21310 21311 declare void @llvm.sideeffect() inaccessiblememonly nounwind 21312 21313Overview: 21314""""""""" 21315 21316The ``llvm.sideeffect`` intrinsic doesn't perform any operation. Optimizers 21317treat it as having side effects, so it can be inserted into a loop to 21318indicate that the loop shouldn't be assumed to terminate (which could 21319potentially lead to the loop being optimized away entirely), even if it's 21320an infinite loop with no other side effects. 21321 21322Arguments: 21323"""""""""" 21324 21325None. 21326 21327Semantics: 21328"""""""""" 21329 21330This intrinsic actually does nothing, but optimizers must assume that it 21331has externally observable side effects. 21332 21333'``llvm.is.constant.*``' Intrinsic 21334^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21335 21336Syntax: 21337""""""" 21338 21339This is an overloaded intrinsic. You can use llvm.is.constant with any argument type. 21340 21341:: 21342 21343 declare i1 @llvm.is.constant.i32(i32 %operand) nounwind readnone 21344 declare i1 @llvm.is.constant.f32(float %operand) nounwind readnone 21345 declare i1 @llvm.is.constant.TYPENAME(TYPE %operand) nounwind readnone 21346 21347Overview: 21348""""""""" 21349 21350The '``llvm.is.constant``' intrinsic will return true if the argument 21351is known to be a manifest compile-time constant. It is guaranteed to 21352fold to either true or false before generating machine code. 21353 21354Semantics: 21355"""""""""" 21356 21357This intrinsic generates no code. If its argument is known to be a 21358manifest compile-time constant value, then the intrinsic will be 21359converted to a constant true value. Otherwise, it will be converted to 21360a constant false value. 21361 21362In particular, note that if the argument is a constant expression 21363which refers to a global (the address of which _is_ a constant, but 21364not manifest during the compile), then the intrinsic evaluates to 21365false. 21366 21367The result also intentionally depends on the result of optimization 21368passes -- e.g., the result can change depending on whether a 21369function gets inlined or not. A function's parameters are 21370obviously not constant. However, a call like 21371``llvm.is.constant.i32(i32 %param)`` *can* return true after the 21372function is inlined, if the value passed to the function parameter was 21373a constant. 21374 21375On the other hand, if constant folding is not run, it will never 21376evaluate to true, even in simple cases. 21377 21378.. _int_ptrmask: 21379 21380'``llvm.ptrmask``' Intrinsic 21381^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21382 21383Syntax: 21384""""""" 21385 21386:: 21387 21388 declare ptrty llvm.ptrmask(ptrty %ptr, intty %mask) readnone speculatable 21389 21390Arguments: 21391"""""""""" 21392 21393The first argument is a pointer. The second argument is an integer. 21394 21395Overview: 21396"""""""""" 21397 21398The ``llvm.ptrmask`` intrinsic masks out bits of the pointer according to a mask. 21399This allows stripping data from tagged pointers without converting them to an 21400integer (ptrtoint/inttoptr). As a consequence, we can preserve more information 21401to facilitate alias analysis and underlying-object detection. 21402 21403Semantics: 21404"""""""""" 21405 21406The result of ``ptrmask(ptr, mask)`` is equivalent to 21407``getelementptr ptr, (ptrtoint(ptr) & mask) - ptrtoint(ptr)``. Both the returned 21408pointer and the first argument are based on the same underlying object (for more 21409information on the *based on* terminology see 21410:ref:`the pointer aliasing rules <pointeraliasing>`). If the bitwidth of the 21411mask argument does not match the pointer size of the target, the mask is 21412zero-extended or truncated accordingly. 21413 21414.. _int_vscale: 21415 21416'``llvm.vscale``' Intrinsic 21417^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21418 21419Syntax: 21420""""""" 21421 21422:: 21423 21424 declare i32 llvm.vscale.i32() 21425 declare i64 llvm.vscale.i64() 21426 21427Overview: 21428""""""""" 21429 21430The ``llvm.vscale`` intrinsic returns the value for ``vscale`` in scalable 21431vectors such as ``<vscale x 16 x i8>``. 21432 21433Semantics: 21434"""""""""" 21435 21436``vscale`` is a positive value that is constant throughout program 21437execution, but is unknown at compile time. 21438If the result value does not fit in the result type, then the result is 21439a :ref:`poison value <poisonvalues>`. 21440 21441 21442Stack Map Intrinsics 21443-------------------- 21444 21445LLVM provides experimental intrinsics to support runtime patching 21446mechanisms commonly desired in dynamic language JITs. These intrinsics 21447are described in :doc:`StackMaps`. 21448 21449Element Wise Atomic Memory Intrinsics 21450------------------------------------- 21451 21452These intrinsics are similar to the standard library memory intrinsics except 21453that they perform memory transfer as a sequence of atomic memory accesses. 21454 21455.. _int_memcpy_element_unordered_atomic: 21456 21457'``llvm.memcpy.element.unordered.atomic``' Intrinsic 21458^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21459 21460Syntax: 21461""""""" 21462 21463This is an overloaded intrinsic. You can use ``llvm.memcpy.element.unordered.atomic`` on 21464any integer bit width and for different address spaces. Not all targets 21465support all bit widths however. 21466 21467:: 21468 21469 declare void @llvm.memcpy.element.unordered.atomic.p0i8.p0i8.i32(i8* <dest>, 21470 i8* <src>, 21471 i32 <len>, 21472 i32 <element_size>) 21473 declare void @llvm.memcpy.element.unordered.atomic.p0i8.p0i8.i64(i8* <dest>, 21474 i8* <src>, 21475 i64 <len>, 21476 i32 <element_size>) 21477 21478Overview: 21479""""""""" 21480 21481The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic is a specialization of the 21482'``llvm.memcpy.*``' intrinsic. It differs in that the ``dest`` and ``src`` are treated 21483as arrays with elements that are exactly ``element_size`` bytes, and the copy between 21484buffers uses a sequence of :ref:`unordered atomic <ordering>` load/store operations 21485that are a positive integer multiple of the ``element_size`` in size. 21486 21487Arguments: 21488"""""""""" 21489 21490The first three arguments are the same as they are in the :ref:`@llvm.memcpy <int_memcpy>` 21491intrinsic, with the added constraint that ``len`` is required to be a positive integer 21492multiple of the ``element_size``. If ``len`` is not a positive integer multiple of 21493``element_size``, then the behaviour of the intrinsic is undefined. 21494 21495``element_size`` must be a compile-time constant positive power of two no greater than 21496target-specific atomic access size limit. 21497 21498For each of the input pointers ``align`` parameter attribute must be specified. It 21499must be a power of two no less than the ``element_size``. Caller guarantees that 21500both the source and destination pointers are aligned to that boundary. 21501 21502Semantics: 21503"""""""""" 21504 21505The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic copies ``len`` bytes of 21506memory from the source location to the destination location. These locations are not 21507allowed to overlap. The memory copy is performed as a sequence of load/store operations 21508where each access is guaranteed to be a multiple of ``element_size`` bytes wide and 21509aligned at an ``element_size`` boundary. 21510 21511The order of the copy is unspecified. The same value may be read from the source 21512buffer many times, but only one write is issued to the destination buffer per 21513element. It is well defined to have concurrent reads and writes to both source and 21514destination provided those reads and writes are unordered atomic when specified. 21515 21516This intrinsic does not provide any additional ordering guarantees over those 21517provided by a set of unordered loads from the source location and stores to the 21518destination. 21519 21520Lowering: 21521""""""""" 21522 21523In the most general case call to the '``llvm.memcpy.element.unordered.atomic.*``' is 21524lowered to a call to the symbol ``__llvm_memcpy_element_unordered_atomic_*``. Where '*' 21525is replaced with an actual element size. See :ref:`RewriteStatepointsForGC intrinsic 21526lowering <RewriteStatepointsForGC_intrinsic_lowering>` for details on GC specific 21527lowering. 21528 21529Optimizer is allowed to inline memory copy when it's profitable to do so. 21530 21531'``llvm.memmove.element.unordered.atomic``' Intrinsic 21532^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21533 21534Syntax: 21535""""""" 21536 21537This is an overloaded intrinsic. You can use 21538``llvm.memmove.element.unordered.atomic`` on any integer bit width and for 21539different address spaces. Not all targets support all bit widths however. 21540 21541:: 21542 21543 declare void @llvm.memmove.element.unordered.atomic.p0i8.p0i8.i32(i8* <dest>, 21544 i8* <src>, 21545 i32 <len>, 21546 i32 <element_size>) 21547 declare void @llvm.memmove.element.unordered.atomic.p0i8.p0i8.i64(i8* <dest>, 21548 i8* <src>, 21549 i64 <len>, 21550 i32 <element_size>) 21551 21552Overview: 21553""""""""" 21554 21555The '``llvm.memmove.element.unordered.atomic.*``' intrinsic is a specialization 21556of the '``llvm.memmove.*``' intrinsic. It differs in that the ``dest`` and 21557``src`` are treated as arrays with elements that are exactly ``element_size`` 21558bytes, and the copy between buffers uses a sequence of 21559:ref:`unordered atomic <ordering>` load/store operations that are a positive 21560integer multiple of the ``element_size`` in size. 21561 21562Arguments: 21563"""""""""" 21564 21565The first three arguments are the same as they are in the 21566:ref:`@llvm.memmove <int_memmove>` intrinsic, with the added constraint that 21567``len`` is required to be a positive integer multiple of the ``element_size``. 21568If ``len`` is not a positive integer multiple of ``element_size``, then the 21569behaviour of the intrinsic is undefined. 21570 21571``element_size`` must be a compile-time constant positive power of two no 21572greater than a target-specific atomic access size limit. 21573 21574For each of the input pointers the ``align`` parameter attribute must be 21575specified. It must be a power of two no less than the ``element_size``. Caller 21576guarantees that both the source and destination pointers are aligned to that 21577boundary. 21578 21579Semantics: 21580"""""""""" 21581 21582The '``llvm.memmove.element.unordered.atomic.*``' intrinsic copies ``len`` bytes 21583of memory from the source location to the destination location. These locations 21584are allowed to overlap. The memory copy is performed as a sequence of load/store 21585operations where each access is guaranteed to be a multiple of ``element_size`` 21586bytes wide and aligned at an ``element_size`` boundary. 21587 21588The order of the copy is unspecified. The same value may be read from the source 21589buffer many times, but only one write is issued to the destination buffer per 21590element. It is well defined to have concurrent reads and writes to both source 21591and destination provided those reads and writes are unordered atomic when 21592specified. 21593 21594This intrinsic does not provide any additional ordering guarantees over those 21595provided by a set of unordered loads from the source location and stores to the 21596destination. 21597 21598Lowering: 21599""""""""" 21600 21601In the most general case call to the 21602'``llvm.memmove.element.unordered.atomic.*``' is lowered to a call to the symbol 21603``__llvm_memmove_element_unordered_atomic_*``. Where '*' is replaced with an 21604actual element size. See :ref:`RewriteStatepointsForGC intrinsic lowering 21605<RewriteStatepointsForGC_intrinsic_lowering>` for details on GC specific 21606lowering. 21607 21608The optimizer is allowed to inline the memory copy when it's profitable to do so. 21609 21610.. _int_memset_element_unordered_atomic: 21611 21612'``llvm.memset.element.unordered.atomic``' Intrinsic 21613^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21614 21615Syntax: 21616""""""" 21617 21618This is an overloaded intrinsic. You can use ``llvm.memset.element.unordered.atomic`` on 21619any integer bit width and for different address spaces. Not all targets 21620support all bit widths however. 21621 21622:: 21623 21624 declare void @llvm.memset.element.unordered.atomic.p0i8.i32(i8* <dest>, 21625 i8 <value>, 21626 i32 <len>, 21627 i32 <element_size>) 21628 declare void @llvm.memset.element.unordered.atomic.p0i8.i64(i8* <dest>, 21629 i8 <value>, 21630 i64 <len>, 21631 i32 <element_size>) 21632 21633Overview: 21634""""""""" 21635 21636The '``llvm.memset.element.unordered.atomic.*``' intrinsic is a specialization of the 21637'``llvm.memset.*``' intrinsic. It differs in that the ``dest`` is treated as an array 21638with elements that are exactly ``element_size`` bytes, and the assignment to that array 21639uses uses a sequence of :ref:`unordered atomic <ordering>` store operations 21640that are a positive integer multiple of the ``element_size`` in size. 21641 21642Arguments: 21643"""""""""" 21644 21645The first three arguments are the same as they are in the :ref:`@llvm.memset <int_memset>` 21646intrinsic, with the added constraint that ``len`` is required to be a positive integer 21647multiple of the ``element_size``. If ``len`` is not a positive integer multiple of 21648``element_size``, then the behaviour of the intrinsic is undefined. 21649 21650``element_size`` must be a compile-time constant positive power of two no greater than 21651target-specific atomic access size limit. 21652 21653The ``dest`` input pointer must have the ``align`` parameter attribute specified. It 21654must be a power of two no less than the ``element_size``. Caller guarantees that 21655the destination pointer is aligned to that boundary. 21656 21657Semantics: 21658"""""""""" 21659 21660The '``llvm.memset.element.unordered.atomic.*``' intrinsic sets the ``len`` bytes of 21661memory starting at the destination location to the given ``value``. The memory is 21662set with a sequence of store operations where each access is guaranteed to be a 21663multiple of ``element_size`` bytes wide and aligned at an ``element_size`` boundary. 21664 21665The order of the assignment is unspecified. Only one write is issued to the 21666destination buffer per element. It is well defined to have concurrent reads and 21667writes to the destination provided those reads and writes are unordered atomic 21668when specified. 21669 21670This intrinsic does not provide any additional ordering guarantees over those 21671provided by a set of unordered stores to the destination. 21672 21673Lowering: 21674""""""""" 21675 21676In the most general case call to the '``llvm.memset.element.unordered.atomic.*``' is 21677lowered to a call to the symbol ``__llvm_memset_element_unordered_atomic_*``. Where '*' 21678is replaced with an actual element size. 21679 21680The optimizer is allowed to inline the memory assignment when it's profitable to do so. 21681 21682Objective-C ARC Runtime Intrinsics 21683---------------------------------- 21684 21685LLVM provides intrinsics that lower to Objective-C ARC runtime entry points. 21686LLVM is aware of the semantics of these functions, and optimizes based on that 21687knowledge. You can read more about the details of Objective-C ARC `here 21688<https://clang.llvm.org/docs/AutomaticReferenceCounting.html>`_. 21689 21690'``llvm.objc.autorelease``' Intrinsic 21691^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21692 21693Syntax: 21694""""""" 21695:: 21696 21697 declare i8* @llvm.objc.autorelease(i8*) 21698 21699Lowering: 21700""""""""" 21701 21702Lowers to a call to `objc_autorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autorelease>`_. 21703 21704'``llvm.objc.autoreleasePoolPop``' Intrinsic 21705^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21706 21707Syntax: 21708""""""" 21709:: 21710 21711 declare void @llvm.objc.autoreleasePoolPop(i8*) 21712 21713Lowering: 21714""""""""" 21715 21716Lowers to a call to `objc_autoreleasePoolPop <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpop-void-pool>`_. 21717 21718'``llvm.objc.autoreleasePoolPush``' Intrinsic 21719^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21720 21721Syntax: 21722""""""" 21723:: 21724 21725 declare i8* @llvm.objc.autoreleasePoolPush() 21726 21727Lowering: 21728""""""""" 21729 21730Lowers to a call to `objc_autoreleasePoolPush <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpush-void>`_. 21731 21732'``llvm.objc.autoreleaseReturnValue``' Intrinsic 21733^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21734 21735Syntax: 21736""""""" 21737:: 21738 21739 declare i8* @llvm.objc.autoreleaseReturnValue(i8*) 21740 21741Lowering: 21742""""""""" 21743 21744Lowers to a call to `objc_autoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autoreleasereturnvalue>`_. 21745 21746'``llvm.objc.copyWeak``' Intrinsic 21747^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21748 21749Syntax: 21750""""""" 21751:: 21752 21753 declare void @llvm.objc.copyWeak(i8**, i8**) 21754 21755Lowering: 21756""""""""" 21757 21758Lowers to a call to `objc_copyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-copyweak-id-dest-id-src>`_. 21759 21760'``llvm.objc.destroyWeak``' Intrinsic 21761^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21762 21763Syntax: 21764""""""" 21765:: 21766 21767 declare void @llvm.objc.destroyWeak(i8**) 21768 21769Lowering: 21770""""""""" 21771 21772Lowers to a call to `objc_destroyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-destroyweak-id-object>`_. 21773 21774'``llvm.objc.initWeak``' Intrinsic 21775^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21776 21777Syntax: 21778""""""" 21779:: 21780 21781 declare i8* @llvm.objc.initWeak(i8**, i8*) 21782 21783Lowering: 21784""""""""" 21785 21786Lowers to a call to `objc_initWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-initweak>`_. 21787 21788'``llvm.objc.loadWeak``' Intrinsic 21789^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21790 21791Syntax: 21792""""""" 21793:: 21794 21795 declare i8* @llvm.objc.loadWeak(i8**) 21796 21797Lowering: 21798""""""""" 21799 21800Lowers to a call to `objc_loadWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweak>`_. 21801 21802'``llvm.objc.loadWeakRetained``' Intrinsic 21803^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21804 21805Syntax: 21806""""""" 21807:: 21808 21809 declare i8* @llvm.objc.loadWeakRetained(i8**) 21810 21811Lowering: 21812""""""""" 21813 21814Lowers to a call to `objc_loadWeakRetained <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweakretained>`_. 21815 21816'``llvm.objc.moveWeak``' Intrinsic 21817^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21818 21819Syntax: 21820""""""" 21821:: 21822 21823 declare void @llvm.objc.moveWeak(i8**, i8**) 21824 21825Lowering: 21826""""""""" 21827 21828Lowers to a call to `objc_moveWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-moveweak-id-dest-id-src>`_. 21829 21830'``llvm.objc.release``' Intrinsic 21831^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21832 21833Syntax: 21834""""""" 21835:: 21836 21837 declare void @llvm.objc.release(i8*) 21838 21839Lowering: 21840""""""""" 21841 21842Lowers to a call to `objc_release <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-release-id-value>`_. 21843 21844'``llvm.objc.retain``' Intrinsic 21845^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21846 21847Syntax: 21848""""""" 21849:: 21850 21851 declare i8* @llvm.objc.retain(i8*) 21852 21853Lowering: 21854""""""""" 21855 21856Lowers to a call to `objc_retain <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retain>`_. 21857 21858'``llvm.objc.retainAutorelease``' Intrinsic 21859^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21860 21861Syntax: 21862""""""" 21863:: 21864 21865 declare i8* @llvm.objc.retainAutorelease(i8*) 21866 21867Lowering: 21868""""""""" 21869 21870Lowers to a call to `objc_retainAutorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautorelease>`_. 21871 21872'``llvm.objc.retainAutoreleaseReturnValue``' Intrinsic 21873^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21874 21875Syntax: 21876""""""" 21877:: 21878 21879 declare i8* @llvm.objc.retainAutoreleaseReturnValue(i8*) 21880 21881Lowering: 21882""""""""" 21883 21884Lowers to a call to `objc_retainAutoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasereturnvalue>`_. 21885 21886'``llvm.objc.retainAutoreleasedReturnValue``' Intrinsic 21887^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21888 21889Syntax: 21890""""""" 21891:: 21892 21893 declare i8* @llvm.objc.retainAutoreleasedReturnValue(i8*) 21894 21895Lowering: 21896""""""""" 21897 21898Lowers to a call to `objc_retainAutoreleasedReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasedreturnvalue>`_. 21899 21900'``llvm.objc.retainBlock``' Intrinsic 21901^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21902 21903Syntax: 21904""""""" 21905:: 21906 21907 declare i8* @llvm.objc.retainBlock(i8*) 21908 21909Lowering: 21910""""""""" 21911 21912Lowers to a call to `objc_retainBlock <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainblock>`_. 21913 21914'``llvm.objc.storeStrong``' Intrinsic 21915^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21916 21917Syntax: 21918""""""" 21919:: 21920 21921 declare void @llvm.objc.storeStrong(i8**, i8*) 21922 21923Lowering: 21924""""""""" 21925 21926Lowers to a call to `objc_storeStrong <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-storestrong-id-object-id-value>`_. 21927 21928'``llvm.objc.storeWeak``' Intrinsic 21929^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21930 21931Syntax: 21932""""""" 21933:: 21934 21935 declare i8* @llvm.objc.storeWeak(i8**, i8*) 21936 21937Lowering: 21938""""""""" 21939 21940Lowers to a call to `objc_storeWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-storeweak>`_. 21941 21942Preserving Debug Information Intrinsics 21943^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21944 21945These intrinsics are used to carry certain debuginfo together with 21946IR-level operations. For example, it may be desirable to 21947know the structure/union name and the original user-level field 21948indices. Such information got lost in IR GetElementPtr instruction 21949since the IR types are different from debugInfo types and unions 21950are converted to structs in IR. 21951 21952'``llvm.preserve.array.access.index``' Intrinsic 21953^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21954 21955Syntax: 21956""""""" 21957:: 21958 21959 declare <ret_type> 21960 @llvm.preserve.array.access.index.p0s_union.anons.p0a10s_union.anons(<type> base, 21961 i32 dim, 21962 i32 index) 21963 21964Overview: 21965""""""""" 21966 21967The '``llvm.preserve.array.access.index``' intrinsic returns the getelementptr address 21968based on array base ``base``, array dimension ``dim`` and the last access index ``index`` 21969into the array. The return type ``ret_type`` is a pointer type to the array element. 21970The array ``dim`` and ``index`` are preserved which is more robust than 21971getelementptr instruction which may be subject to compiler transformation. 21972The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction 21973to provide array or pointer debuginfo type. 21974The metadata is a ``DICompositeType`` or ``DIDerivedType`` representing the 21975debuginfo version of ``type``. 21976 21977Arguments: 21978"""""""""" 21979 21980The ``base`` is the array base address. The ``dim`` is the array dimension. 21981The ``base`` is a pointer if ``dim`` equals 0. 21982The ``index`` is the last access index into the array or pointer. 21983 21984Semantics: 21985"""""""""" 21986 21987The '``llvm.preserve.array.access.index``' intrinsic produces the same result 21988as a getelementptr with base ``base`` and access operands ``{dim's 0's, index}``. 21989 21990'``llvm.preserve.union.access.index``' Intrinsic 21991^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21992 21993Syntax: 21994""""""" 21995:: 21996 21997 declare <type> 21998 @llvm.preserve.union.access.index.p0s_union.anons.p0s_union.anons(<type> base, 21999 i32 di_index) 22000 22001Overview: 22002""""""""" 22003 22004The '``llvm.preserve.union.access.index``' intrinsic carries the debuginfo field index 22005``di_index`` and returns the ``base`` address. 22006The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction 22007to provide union debuginfo type. 22008The metadata is a ``DICompositeType`` representing the debuginfo version of ``type``. 22009The return type ``type`` is the same as the ``base`` type. 22010 22011Arguments: 22012"""""""""" 22013 22014The ``base`` is the union base address. The ``di_index`` is the field index in debuginfo. 22015 22016Semantics: 22017"""""""""" 22018 22019The '``llvm.preserve.union.access.index``' intrinsic returns the ``base`` address. 22020 22021'``llvm.preserve.struct.access.index``' Intrinsic 22022^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22023 22024Syntax: 22025""""""" 22026:: 22027 22028 declare <ret_type> 22029 @llvm.preserve.struct.access.index.p0i8.p0s_struct.anon.0s(<type> base, 22030 i32 gep_index, 22031 i32 di_index) 22032 22033Overview: 22034""""""""" 22035 22036The '``llvm.preserve.struct.access.index``' intrinsic returns the getelementptr address 22037based on struct base ``base`` and IR struct member index ``gep_index``. 22038The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction 22039to provide struct debuginfo type. 22040The metadata is a ``DICompositeType`` representing the debuginfo version of ``type``. 22041The return type ``ret_type`` is a pointer type to the structure member. 22042 22043Arguments: 22044"""""""""" 22045 22046The ``base`` is the structure base address. The ``gep_index`` is the struct member index 22047based on IR structures. The ``di_index`` is the struct member index based on debuginfo. 22048 22049Semantics: 22050"""""""""" 22051 22052The '``llvm.preserve.struct.access.index``' intrinsic produces the same result 22053as a getelementptr with base ``base`` and access operands ``{0, gep_index}``. 22054