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(ptr nocapture) nounwind 161 162 ; Definition of main function 163 define i32 @main() { 164 ; Call puts function to write out the string to stdout. 165 call i32 @puts(ptr @.str) 166 ret i32 0 167 } 168 169 ; Named metadata 170 !0 = !{i32 42, null, !"string"} 171 !foo = !{!0} 172 173This example is made up of a :ref:`global variable <globalvars>` named 174"``.str``", an external declaration of the "``puts``" function, a 175:ref:`function definition <functionstructure>` for "``main``" and 176:ref:`named metadata <namedmetadatastructure>` "``foo``". 177 178In general, a module is made up of a list of global values (where both 179functions and global variables are global values). Global values are 180represented by a pointer to a memory location (in this case, a pointer 181to an array of char, and a pointer to a function), and have one of the 182following :ref:`linkage types <linkage>`. 183 184.. _linkage: 185 186Linkage Types 187------------- 188 189All Global Variables and Functions have one of the following types of 190linkage: 191 192``private`` 193 Global values with "``private``" linkage are only directly 194 accessible by objects in the current module. In particular, linking 195 code into a module with a private global value may cause the 196 private to be renamed as necessary to avoid collisions. Because the 197 symbol is private to the module, all references can be updated. This 198 doesn't show up in any symbol table in the object file. 199``internal`` 200 Similar to private, but the value shows as a local symbol 201 (``STB_LOCAL`` in the case of ELF) in the object file. This 202 corresponds to the notion of the '``static``' keyword in C. 203``available_externally`` 204 Globals with "``available_externally``" linkage are never emitted into 205 the object file corresponding to the LLVM module. From the linker's 206 perspective, an ``available_externally`` global is equivalent to 207 an external declaration. They exist to allow inlining and other 208 optimizations to take place given knowledge of the definition of the 209 global, which is known to be somewhere outside the module. Globals 210 with ``available_externally`` linkage are allowed to be discarded at 211 will, and allow inlining and other optimizations. This linkage type is 212 only allowed on definitions, not declarations. 213``linkonce`` 214 Globals with "``linkonce``" linkage are merged with other globals of 215 the same name when linkage occurs. This can be used to implement 216 some forms of inline functions, templates, or other code which must 217 be generated in each translation unit that uses it, but where the 218 body may be overridden with a more definitive definition later. 219 Unreferenced ``linkonce`` globals are allowed to be discarded. Note 220 that ``linkonce`` linkage does not actually allow the optimizer to 221 inline the body of this function into callers because it doesn't 222 know if this definition of the function is the definitive definition 223 within the program or whether it will be overridden by a stronger 224 definition. To enable inlining and other optimizations, use 225 "``linkonce_odr``" linkage. 226``weak`` 227 "``weak``" linkage has the same merging semantics as ``linkonce`` 228 linkage, except that unreferenced globals with ``weak`` linkage may 229 not be discarded. This is used for globals that are declared "weak" 230 in C source code. 231``common`` 232 "``common``" linkage is most similar to "``weak``" linkage, but they 233 are used for tentative definitions in C, such as "``int X;``" at 234 global scope. Symbols with "``common``" linkage are merged in the 235 same way as ``weak symbols``, and they may not be deleted if 236 unreferenced. ``common`` symbols may not have an explicit section, 237 must have a zero initializer, and may not be marked 238 ':ref:`constant <globalvars>`'. Functions and aliases may not have 239 common linkage. 240 241.. _linkage_appending: 242 243``appending`` 244 "``appending``" linkage may only be applied to global variables of 245 pointer to array type. When two global variables with appending 246 linkage are linked together, the two global arrays are appended 247 together. This is the LLVM, typesafe, equivalent of having the 248 system linker append together "sections" with identical names when 249 .o files are linked. 250 251 Unfortunately this doesn't correspond to any feature in .o files, so it 252 can only be used for variables like ``llvm.global_ctors`` which llvm 253 interprets specially. 254 255``extern_weak`` 256 The semantics of this linkage follow the ELF object file model: the 257 symbol is weak until linked, if not linked, the symbol becomes null 258 instead of being an undefined reference. 259``linkonce_odr``, ``weak_odr`` 260 Some languages allow differing globals to be merged, such as two 261 functions with different semantics. Other languages, such as 262 ``C++``, ensure that only equivalent globals are ever merged (the 263 "one definition rule" --- "ODR"). Such languages can use the 264 ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the 265 global will only be merged with equivalent globals. These linkage 266 types are otherwise the same as their non-``odr`` versions. 267``external`` 268 If none of the above identifiers are used, the global is externally 269 visible, meaning that it participates in linkage and can be used to 270 resolve external symbol references. 271 272It is illegal for a global variable or function *declaration* to have any 273linkage type other than ``external`` or ``extern_weak``. 274 275.. _callingconv: 276 277Calling Conventions 278------------------- 279 280LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and 281:ref:`invokes <i_invoke>` can all have an optional calling convention 282specified for the call. The calling convention of any pair of dynamic 283caller/callee must match, or the behavior of the program is undefined. 284The following calling conventions are supported by LLVM, and more may be 285added in the future: 286 287"``ccc``" - The C calling convention 288 This calling convention (the default if no other calling convention 289 is specified) matches the target C calling conventions. This calling 290 convention supports varargs function calls and tolerates some 291 mismatch in the declared prototype and implemented declaration of 292 the function (as does normal C). 293"``fastcc``" - The fast calling convention 294 This calling convention attempts to make calls as fast as possible 295 (e.g. by passing things in registers). This calling convention 296 allows the target to use whatever tricks it wants to produce fast 297 code for the target, without having to conform to an externally 298 specified ABI (Application Binary Interface). `Tail calls can only 299 be optimized when this, the tailcc, the GHC or the HiPE convention is 300 used. <CodeGenerator.html#tail-call-optimization>`_ This calling 301 convention does not support varargs and requires the prototype of all 302 callees to exactly match the prototype of the function definition. 303"``coldcc``" - The cold calling convention 304 This calling convention attempts to make code in the caller as 305 efficient as possible under the assumption that the call is not 306 commonly executed. As such, these calls often preserve all registers 307 so that the call does not break any live ranges in the caller side. 308 This calling convention does not support varargs and requires the 309 prototype of all callees to exactly match the prototype of the 310 function definition. Furthermore the inliner doesn't consider such function 311 calls for inlining. 312"``cc 10``" - GHC convention 313 This calling convention has been implemented specifically for use by 314 the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_. 315 It passes everything in registers, going to extremes to achieve this 316 by disabling callee save registers. This calling convention should 317 not be used lightly but only for specific situations such as an 318 alternative to the *register pinning* performance technique often 319 used when implementing functional programming languages. At the 320 moment only X86 supports this convention and it has the following 321 limitations: 322 323 - On *X86-32* only supports up to 4 bit type parameters. No 324 floating-point types are supported. 325 - On *X86-64* only supports up to 10 bit type parameters and 6 326 floating-point parameters. 327 328 This calling convention supports `tail call 329 optimization <CodeGenerator.html#tail-call-optimization>`_ but requires 330 both the caller and callee are using it. 331"``cc 11``" - The HiPE calling convention 332 This calling convention has been implemented specifically for use by 333 the `High-Performance Erlang 334 (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the* 335 native code compiler of the `Ericsson's Open Source Erlang/OTP 336 system <http://www.erlang.org/download.shtml>`_. It uses more 337 registers for argument passing than the ordinary C calling 338 convention and defines no callee-saved registers. The calling 339 convention properly supports `tail call 340 optimization <CodeGenerator.html#tail-call-optimization>`_ but requires 341 that both the caller and the callee use it. It uses a *register pinning* 342 mechanism, similar to GHC's convention, for keeping frequently 343 accessed runtime components pinned to specific hardware registers. 344 At the moment only X86 supports this convention (both 32 and 64 345 bit). 346"``webkit_jscc``" - WebKit's JavaScript calling convention 347 This calling convention has been implemented for `WebKit FTL JIT 348 <https://trac.webkit.org/wiki/FTLJIT>`_. It passes arguments on the 349 stack right to left (as cdecl does), and returns a value in the 350 platform's customary return register. 351"``anyregcc``" - Dynamic calling convention for code patching 352 This is a special convention that supports patching an arbitrary code 353 sequence in place of a call site. This convention forces the call 354 arguments into registers but allows them to be dynamically 355 allocated. This can currently only be used with calls to 356 llvm.experimental.patchpoint because only this intrinsic records 357 the location of its arguments in a side table. See :doc:`StackMaps`. 358"``preserve_mostcc``" - The `PreserveMost` calling convention 359 This calling convention attempts to make the code in the caller as 360 unintrusive as possible. This convention behaves identically to the `C` 361 calling convention on how arguments and return values are passed, but it 362 uses a different set of caller/callee-saved registers. This alleviates the 363 burden of saving and recovering a large register set before and after the 364 call in the caller. If the arguments are passed in callee-saved registers, 365 then they will be preserved by the callee across the call. This doesn't 366 apply for values returned in callee-saved registers. 367 368 - On X86-64 the callee preserves all general purpose registers, except for 369 R11. R11 can be used as a scratch register. Floating-point registers 370 (XMMs/YMMs) are not preserved and need to be saved by the caller. 371 372 The idea behind this convention is to support calls to runtime functions 373 that have a hot path and a cold path. The hot path is usually a small piece 374 of code that doesn't use many registers. The cold path might need to call out to 375 another function and therefore only needs to preserve the caller-saved 376 registers, which haven't already been saved by the caller. The 377 `PreserveMost` calling convention is very similar to the `cold` calling 378 convention in terms of caller/callee-saved registers, but they are used for 379 different types of function calls. `coldcc` is for function calls that are 380 rarely executed, whereas `preserve_mostcc` function calls are intended to be 381 on the hot path and definitely executed a lot. Furthermore `preserve_mostcc` 382 doesn't prevent the inliner from inlining the function call. 383 384 This calling convention will be used by a future version of the ObjectiveC 385 runtime and should therefore still be considered experimental at this time. 386 Although this convention was created to optimize certain runtime calls to 387 the ObjectiveC runtime, it is not limited to this runtime and might be used 388 by other runtimes in the future too. The current implementation only 389 supports X86-64, but the intention is to support more architectures in the 390 future. 391"``preserve_allcc``" - The `PreserveAll` calling convention 392 This calling convention attempts to make the code in the caller even less 393 intrusive than the `PreserveMost` calling convention. This calling 394 convention also behaves identical to the `C` calling convention on how 395 arguments and return values are passed, but it uses a different set of 396 caller/callee-saved registers. This removes the burden of saving and 397 recovering a large register set before and after the call in the caller. If 398 the arguments are passed in callee-saved registers, then they will be 399 preserved by the callee across the call. This doesn't apply for values 400 returned in callee-saved registers. 401 402 - On X86-64 the callee preserves all general purpose registers, except for 403 R11. R11 can be used as a scratch register. Furthermore it also preserves 404 all floating-point registers (XMMs/YMMs). 405 406 The idea behind this convention is to support calls to runtime functions 407 that don't need to call out to any other functions. 408 409 This calling convention, like the `PreserveMost` calling convention, will be 410 used by a future version of the ObjectiveC runtime and should be considered 411 experimental at this time. 412"``cxx_fast_tlscc``" - The `CXX_FAST_TLS` calling convention for access functions 413 Clang generates an access function to access C++-style TLS. The access 414 function generally has an entry block, an exit block and an initialization 415 block that is run at the first time. The entry and exit blocks can access 416 a few TLS IR variables, each access will be lowered to a platform-specific 417 sequence. 418 419 This calling convention aims to minimize overhead in the caller by 420 preserving as many registers as possible (all the registers that are 421 preserved on the fast path, composed of the entry and exit blocks). 422 423 This calling convention behaves identical to the `C` calling convention on 424 how arguments and return values are passed, but it uses a different set of 425 caller/callee-saved registers. 426 427 Given that each platform has its own lowering sequence, hence its own set 428 of preserved registers, we can't use the existing `PreserveMost`. 429 430 - On X86-64 the callee preserves all general purpose registers, except for 431 RDI and RAX. 432"``tailcc``" - Tail callable calling convention 433 This calling convention ensures that calls in tail position will always be 434 tail call optimized. This calling convention is equivalent to fastcc, 435 except for an additional guarantee that tail calls will be produced 436 whenever possible. `Tail calls can only be optimized when this, the fastcc, 437 the GHC or the HiPE convention is used. <CodeGenerator.html#tail-call-optimization>`_ 438 This calling convention does not support varargs and requires the prototype of 439 all callees to exactly match the prototype of the function definition. 440"``swiftcc``" - This calling convention is used for Swift language. 441 - On X86-64 RCX and R8 are available for additional integer returns, and 442 XMM2 and XMM3 are available for additional FP/vector returns. 443 - On iOS platforms, we use AAPCS-VFP calling convention. 444"``swifttailcc``" 445 This calling convention is like ``swiftcc`` in most respects, but also the 446 callee pops the argument area of the stack so that mandatory tail calls are 447 possible as in ``tailcc``. 448"``cfguard_checkcc``" - Windows Control Flow Guard (Check mechanism) 449 This calling convention is used for the Control Flow Guard check function, 450 calls to which can be inserted before indirect calls to check that the call 451 target is a valid function address. The check function has no return value, 452 but it will trigger an OS-level error if the address is not a valid target. 453 The set of registers preserved by the check function, and the register 454 containing the target address are architecture-specific. 455 456 - On X86 the target address is passed in ECX. 457 - On ARM the target address is passed in R0. 458 - On AArch64 the target address is passed in X15. 459"``cc <n>``" - Numbered convention 460 Any calling convention may be specified by number, allowing 461 target-specific calling conventions to be used. Target specific 462 calling conventions start at 64. 463 464More calling conventions can be added/defined on an as-needed basis, to 465support Pascal conventions or any other well-known target-independent 466convention. 467 468.. _visibilitystyles: 469 470Visibility Styles 471----------------- 472 473All Global Variables and Functions have one of the following visibility 474styles: 475 476"``default``" - Default style 477 On targets that use the ELF object file format, default visibility 478 means that the declaration is visible to other modules and, in 479 shared libraries, means that the declared entity may be overridden. 480 On Darwin, default visibility means that the declaration is visible 481 to other modules. On XCOFF, default visibility means no explicit 482 visibility bit will be set and whether the symbol is visible 483 (i.e "exported") to other modules depends primarily on export lists 484 provided to the linker. Default visibility corresponds to "external 485 linkage" in the language. 486"``hidden``" - Hidden style 487 Two declarations of an object with hidden visibility refer to the 488 same object if they are in the same shared object. Usually, hidden 489 visibility indicates that the symbol will not be placed into the 490 dynamic symbol table, so no other module (executable or shared 491 library) can reference it directly. 492"``protected``" - Protected style 493 On ELF, protected visibility indicates that the symbol will be 494 placed in the dynamic symbol table, but that references within the 495 defining module will bind to the local symbol. That is, the symbol 496 cannot be overridden by another module. 497 498A symbol with ``internal`` or ``private`` linkage must have ``default`` 499visibility. 500 501.. _dllstorageclass: 502 503DLL Storage Classes 504------------------- 505 506All Global Variables, Functions and Aliases can have one of the following 507DLL storage class: 508 509``dllimport`` 510 "``dllimport``" causes the compiler to reference a function or variable via 511 a global pointer to a pointer that is set up by the DLL exporting the 512 symbol. On Microsoft Windows targets, the pointer name is formed by 513 combining ``__imp_`` and the function or variable name. 514``dllexport`` 515 On Microsoft Windows targets, "``dllexport``" causes the compiler to provide 516 a global pointer to a pointer in a DLL, so that it can be referenced with the 517 ``dllimport`` attribute. the pointer name is formed by combining ``__imp_`` 518 and the function or variable name. On XCOFF targets, ``dllexport`` indicates 519 that the symbol will be made visible to other modules using "exported" 520 visibility and thus placed by the linker in the loader section symbol table. 521 Since this storage class exists for defining a dll interface, the compiler, 522 assembler and linker know it is externally referenced and must refrain from 523 deleting the symbol. 524 525.. _tls_model: 526 527Thread Local Storage Models 528--------------------------- 529 530A variable may be defined as ``thread_local``, which means that it will 531not be shared by threads (each thread will have a separated copy of the 532variable). Not all targets support thread-local variables. Optionally, a 533TLS model may be specified: 534 535``localdynamic`` 536 For variables that are only used within the current shared library. 537``initialexec`` 538 For variables in modules that will not be loaded dynamically. 539``localexec`` 540 For variables defined in the executable and only used within it. 541 542If no explicit model is given, the "general dynamic" model is used. 543 544The models correspond to the ELF TLS models; see `ELF Handling For 545Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for 546more information on under which circumstances the different models may 547be used. The target may choose a different TLS model if the specified 548model is not supported, or if a better choice of model can be made. 549 550A model can also be specified in an alias, but then it only governs how 551the alias is accessed. It will not have any effect in the aliasee. 552 553For platforms without linker support of ELF TLS model, the -femulated-tls 554flag can be used to generate GCC compatible emulated TLS code. 555 556.. _runtime_preemption_model: 557 558Runtime Preemption Specifiers 559----------------------------- 560 561Global variables, functions and aliases may have an optional runtime preemption 562specifier. If a preemption specifier isn't given explicitly, then a 563symbol is assumed to be ``dso_preemptable``. 564 565``dso_preemptable`` 566 Indicates that the function or variable may be replaced by a symbol from 567 outside the linkage unit at runtime. 568 569``dso_local`` 570 The compiler may assume that a function or variable marked as ``dso_local`` 571 will resolve to a symbol within the same linkage unit. Direct access will 572 be generated even if the definition is not within this compilation unit. 573 574.. _namedtypes: 575 576Structure Types 577--------------- 578 579LLVM IR allows you to specify both "identified" and "literal" :ref:`structure 580types <t_struct>`. Literal types are uniqued structurally, but identified types 581are never uniqued. An :ref:`opaque structural type <t_opaque>` can also be used 582to forward declare a type that is not yet available. 583 584An example of an identified structure specification is: 585 586.. code-block:: llvm 587 588 %mytype = type { %mytype*, i32 } 589 590Prior to the LLVM 3.0 release, identified types were structurally uniqued. Only 591literal types are uniqued in recent versions of LLVM. 592 593.. _nointptrtype: 594 595Non-Integral Pointer Type 596------------------------- 597 598Note: non-integral pointer types are a work in progress, and they should be 599considered experimental at this time. 600 601LLVM IR optionally allows the frontend to denote pointers in certain address 602spaces as "non-integral" via the :ref:`datalayout string<langref_datalayout>`. 603Non-integral pointer types represent pointers that have an *unspecified* bitwise 604representation; that is, the integral representation may be target dependent or 605unstable (not backed by a fixed integer). 606 607``inttoptr`` and ``ptrtoint`` instructions have the same semantics as for 608integral (i.e. normal) pointers in that they convert integers to and from 609corresponding pointer types, but there are additional implications to be 610aware of. Because the bit-representation of a non-integral pointer may 611not be stable, two identical casts of the same operand may or may not 612return the same value. Said differently, the conversion to or from the 613non-integral type depends on environmental state in an implementation 614defined manner. 615 616If the frontend wishes to observe a *particular* value following a cast, the 617generated IR must fence with the underlying environment in an implementation 618defined manner. (In practice, this tends to require ``noinline`` routines for 619such operations.) 620 621From the perspective of the optimizer, ``inttoptr`` and ``ptrtoint`` for 622non-integral types are analogous to ones on integral types with one 623key exception: the optimizer may not, in general, insert new dynamic 624occurrences of such casts. If a new cast is inserted, the optimizer would 625need to either ensure that a) all possible values are valid, or b) 626appropriate fencing is inserted. Since the appropriate fencing is 627implementation defined, the optimizer can't do the latter. The former is 628challenging as many commonly expected properties, such as 629``ptrtoint(v)-ptrtoint(v) == 0``, don't hold for non-integral types. 630 631.. _globalvars: 632 633Global Variables 634---------------- 635 636Global variables define regions of memory allocated at compilation time 637instead of run-time. 638 639Global variable definitions must be initialized. 640 641Global variables in other translation units can also be declared, in which 642case they don't have an initializer. 643 644Global variables can optionally specify a :ref:`linkage type <linkage>`. 645 646Either global variable definitions or declarations may have an explicit section 647to be placed in and may have an optional explicit alignment specified. If there 648is a mismatch between the explicit or inferred section information for the 649variable declaration and its definition the resulting behavior is undefined. 650 651A variable may be defined as a global ``constant``, which indicates that 652the contents of the variable will **never** be modified (enabling better 653optimization, allowing the global data to be placed in the read-only 654section of an executable, etc). Note that variables that need runtime 655initialization cannot be marked ``constant`` as there is a store to the 656variable. 657 658LLVM explicitly allows *declarations* of global variables to be marked 659constant, even if the final definition of the global is not. This 660capability can be used to enable slightly better optimization of the 661program, but requires the language definition to guarantee that 662optimizations based on the 'constantness' are valid for the translation 663units that do not include the definition. 664 665As SSA values, global variables define pointer values that are in scope 666(i.e. they dominate) all basic blocks in the program. Global variables 667always define a pointer to their "content" type because they describe a 668region of memory, and all memory objects in LLVM are accessed through 669pointers. 670 671Global variables can be marked with ``unnamed_addr`` which indicates 672that the address is not significant, only the content. Constants marked 673like this can be merged with other constants if they have the same 674initializer. Note that a constant with significant address *can* be 675merged with a ``unnamed_addr`` constant, the result being a constant 676whose address is significant. 677 678If the ``local_unnamed_addr`` attribute is given, the address is known to 679not be significant within the module. 680 681A global variable may be declared to reside in a target-specific 682numbered address space. For targets that support them, address spaces 683may affect how optimizations are performed and/or what target 684instructions are used to access the variable. The default address space 685is zero. The address space qualifier must precede any other attributes. 686 687LLVM allows an explicit section to be specified for globals. If the 688target supports it, it will emit globals to the section specified. 689Additionally, the global can placed in a comdat if the target has the necessary 690support. 691 692External declarations may have an explicit section specified. Section 693information is retained in LLVM IR for targets that make use of this 694information. Attaching section information to an external declaration is an 695assertion that its definition is located in the specified section. If the 696definition is located in a different section, the behavior is undefined. 697 698By default, global initializers are optimized by assuming that global 699variables defined within the module are not modified from their 700initial values before the start of the global initializer. This is 701true even for variables potentially accessible from outside the 702module, including those with external linkage or appearing in 703``@llvm.used`` or dllexported variables. This assumption may be suppressed 704by marking the variable with ``externally_initialized``. 705 706An explicit alignment may be specified for a global, which must be a 707power of 2. If not present, or if the alignment is set to zero, the 708alignment of the global is set by the target to whatever it feels 709convenient. If an explicit alignment is specified, the global is forced 710to have exactly that alignment. Targets and optimizers are not allowed 711to over-align the global if the global has an assigned section. In this 712case, the extra alignment could be observable: for example, code could 713assume that the globals are densely packed in their section and try to 714iterate over them as an array, alignment padding would break this 715iteration. The maximum alignment is ``1 << 32``. 716 717For global variables declarations, as well as definitions that may be 718replaced at link time (``linkonce``, ``weak``, ``extern_weak`` and ``common`` 719linkage types), LLVM makes no assumptions about the allocation size of the 720variables, except that they may not overlap. The alignment of a global variable 721declaration or replaceable definition must not be greater than the alignment of 722the definition it resolves to. 723 724Globals can also have a :ref:`DLL storage class <dllstorageclass>`, 725an optional :ref:`runtime preemption specifier <runtime_preemption_model>`, 726an optional :ref:`global attributes <glattrs>` and 727an optional list of attached :ref:`metadata <metadata>`. 728 729Variables and aliases can have a 730:ref:`Thread Local Storage Model <tls_model>`. 731 732:ref:`Scalable vectors <t_vector>` cannot be global variables or members of 733arrays because their size is unknown at compile time. They are allowed in 734structs to facilitate intrinsics returning multiple values. Structs containing 735scalable vectors cannot be used in loads, stores, allocas, or GEPs. 736 737Syntax:: 738 739 @<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility] 740 [DLLStorageClass] [ThreadLocal] 741 [(unnamed_addr|local_unnamed_addr)] [AddrSpace] 742 [ExternallyInitialized] 743 <global | constant> <Type> [<InitializerConstant>] 744 [, section "name"] [, partition "name"] 745 [, comdat [($name)]] [, align <Alignment>] 746 [, no_sanitize_address] [, no_sanitize_hwaddress] 747 [, sanitize_address_dyninit] [, sanitize_memtag] 748 (, !name !N)* 749 750For example, the following defines a global in a numbered address space 751with an initializer, section, and alignment: 752 753.. code-block:: llvm 754 755 @G = addrspace(5) constant float 1.0, section "foo", align 4 756 757The following example just declares a global variable 758 759.. code-block:: llvm 760 761 @G = external global i32 762 763The following example defines a thread-local global with the 764``initialexec`` TLS model: 765 766.. code-block:: llvm 767 768 @G = thread_local(initialexec) global i32 0, align 4 769 770.. _functionstructure: 771 772Functions 773--------- 774 775LLVM function definitions consist of the "``define``" keyword, an 776optional :ref:`linkage type <linkage>`, an optional :ref:`runtime preemption 777specifier <runtime_preemption_model>`, an optional :ref:`visibility 778style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, 779an optional :ref:`calling convention <callingconv>`, 780an optional ``unnamed_addr`` attribute, a return type, an optional 781:ref:`parameter attribute <paramattrs>` for the return type, a function 782name, a (possibly empty) argument list (each with optional :ref:`parameter 783attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`, 784an optional address space, an optional section, an optional partition, 785an optional alignment, an optional :ref:`comdat <langref_comdats>`, 786an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`, 787an optional :ref:`prologue <prologuedata>`, 788an optional :ref:`personality <personalityfn>`, 789an optional list of attached :ref:`metadata <metadata>`, 790an opening curly brace, a list of basic blocks, and a closing curly brace. 791 792Syntax:: 793 794 define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass] 795 [cconv] [ret attrs] 796 <ResultType> @<FunctionName> ([argument list]) 797 [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs] 798 [section "name"] [partition "name"] [comdat [($name)]] [align N] 799 [gc] [prefix Constant] [prologue Constant] [personality Constant] 800 (!name !N)* { ... } 801 802The argument list is a comma separated sequence of arguments where each 803argument is of the following form: 804 805Syntax:: 806 807 <type> [parameter Attrs] [name] 808 809LLVM function declarations consist of the "``declare``" keyword, an 810optional :ref:`linkage type <linkage>`, an optional :ref:`visibility style 811<visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, an 812optional :ref:`calling convention <callingconv>`, an optional ``unnamed_addr`` 813or ``local_unnamed_addr`` attribute, an optional address space, a return type, 814an optional :ref:`parameter attribute <paramattrs>` for the return type, a function name, a possibly 815empty list of arguments, an optional alignment, an optional :ref:`garbage 816collector name <gc>`, an optional :ref:`prefix <prefixdata>`, and an optional 817:ref:`prologue <prologuedata>`. 818 819Syntax:: 820 821 declare [linkage] [visibility] [DLLStorageClass] 822 [cconv] [ret attrs] 823 <ResultType> @<FunctionName> ([argument list]) 824 [(unnamed_addr|local_unnamed_addr)] [align N] [gc] 825 [prefix Constant] [prologue Constant] 826 827A function definition contains a list of basic blocks, forming the CFG (Control 828Flow Graph) for the function. Each basic block may optionally start with a label 829(giving the basic block a symbol table entry), contains a list of instructions, 830and ends with a :ref:`terminator <terminators>` instruction (such as a branch or 831function return). If an explicit label name is not provided, a block is assigned 832an implicit numbered label, using the next value from the same counter as used 833for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a 834function entry block does not have an explicit label, it will be assigned label 835"%0", then the first unnamed temporary in that block will be "%1", etc. If a 836numeric label is explicitly specified, it must match the numeric label that 837would be used implicitly. 838 839The first basic block in a function is special in two ways: it is 840immediately executed on entrance to the function, and it is not allowed 841to have predecessor basic blocks (i.e. there can not be any branches to 842the entry block of a function). Because the block can have no 843predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`. 844 845LLVM allows an explicit section to be specified for functions. If the 846target supports it, it will emit functions to the section specified. 847Additionally, the function can be placed in a COMDAT. 848 849An explicit alignment may be specified for a function. If not present, 850or if the alignment is set to zero, the alignment of the function is set 851by the target to whatever it feels convenient. If an explicit alignment 852is specified, the function is forced to have at least that much 853alignment. All alignments must be a power of 2. 854 855If the ``unnamed_addr`` attribute is given, the address is known to not 856be significant and two identical functions can be merged. 857 858If the ``local_unnamed_addr`` attribute is given, the address is known to 859not be significant within the module. 860 861If an explicit address space is not given, it will default to the program 862address space from the :ref:`datalayout string<langref_datalayout>`. 863 864.. _langref_aliases: 865 866Aliases 867------- 868 869Aliases, unlike function or variables, don't create any new data. They 870are just a new symbol and metadata for an existing position. 871 872Aliases have a name and an aliasee that is either a global value or a 873constant expression. 874 875Aliases may have an optional :ref:`linkage type <linkage>`, an optional 876:ref:`runtime preemption specifier <runtime_preemption_model>`, an optional 877:ref:`visibility style <visibility>`, an optional :ref:`DLL storage class 878<dllstorageclass>` and an optional :ref:`tls model <tls_model>`. 879 880Syntax:: 881 882 @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee> 883 [, partition "name"] 884 885The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``, 886``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers 887might not correctly handle dropping a weak symbol that is aliased. 888 889Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as 890the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point 891to the same content. 892 893If the ``local_unnamed_addr`` attribute is given, the address is known to 894not be significant within the module. 895 896Since aliases are only a second name, some restrictions apply, of which 897some can only be checked when producing an object file: 898 899* The expression defining the aliasee must be computable at assembly 900 time. Since it is just a name, no relocations can be used. 901 902* No alias in the expression can be weak as the possibility of the 903 intermediate alias being overridden cannot be represented in an 904 object file. 905 906* No global value in the expression can be a declaration, since that 907 would require a relocation, which is not possible. 908 909* If either the alias or the aliasee may be replaced by a symbol outside the 910 module at link time or runtime, any optimization cannot replace the alias with 911 the aliasee, since the behavior may be different. The alias may be used as a 912 name guaranteed to point to the content in the current module. 913 914.. _langref_ifunc: 915 916IFuncs 917------- 918 919IFuncs, like as aliases, don't create any new data or func. They are just a new 920symbol that dynamic linker resolves at runtime by calling a resolver function. 921 922IFuncs have a name and a resolver that is a function called by dynamic linker 923that returns address of another function associated with the name. 924 925IFunc may have an optional :ref:`linkage type <linkage>` and an optional 926:ref:`visibility style <visibility>`. 927 928Syntax:: 929 930 @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver> 931 [, partition "name"] 932 933 934.. _langref_comdats: 935 936Comdats 937------- 938 939Comdat IR provides access to object file COMDAT/section group functionality 940which represents interrelated sections. 941 942Comdats have a name which represents the COMDAT key and a selection kind to 943provide input on how the linker deduplicates comdats with the same key in two 944different object files. A comdat must be included or omitted as a unit. 945Discarding the whole comdat is allowed but discarding a subset is not. 946 947A global object may be a member of at most one comdat. Aliases are placed in the 948same COMDAT that their aliasee computes to, if any. 949 950Syntax:: 951 952 $<Name> = comdat SelectionKind 953 954For selection kinds other than ``nodeduplicate``, only one of the duplicate 955comdats may be retained by the linker and the members of the remaining comdats 956must be discarded. The following selection kinds are supported: 957 958``any`` 959 The linker may choose any COMDAT key, the choice is arbitrary. 960``exactmatch`` 961 The linker may choose any COMDAT key but the sections must contain the 962 same data. 963``largest`` 964 The linker will choose the section containing the largest COMDAT key. 965``nodeduplicate`` 966 No deduplication is performed. 967``samesize`` 968 The linker may choose any COMDAT key but the sections must contain the 969 same amount of data. 970 971- XCOFF and Mach-O don't support COMDATs. 972- COFF supports all selection kinds. Non-``nodeduplicate`` selection kinds need 973 a non-local linkage COMDAT symbol. 974- ELF supports ``any`` and ``nodeduplicate``. 975- WebAssembly only supports ``any``. 976 977Here is an example of a COFF COMDAT where a function will only be selected if 978the COMDAT key's section is the largest: 979 980.. code-block:: text 981 982 $foo = comdat largest 983 @foo = global i32 2, comdat($foo) 984 985 define void @bar() comdat($foo) { 986 ret void 987 } 988 989In a COFF object file, this will create a COMDAT section with selection kind 990``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol 991and another COMDAT section with selection kind 992``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT 993section and contains the contents of the ``@bar`` symbol. 994 995As a syntactic sugar the ``$name`` can be omitted if the name is the same as 996the global name: 997 998.. code-block:: llvm 999 1000 $foo = comdat any 1001 @foo = global i32 2, comdat 1002 @bar = global i32 3, comdat($foo) 1003 1004There are some restrictions on the properties of the global object. 1005It, or an alias to it, must have the same name as the COMDAT group when 1006targeting COFF. 1007The contents and size of this object may be used during link-time to determine 1008which COMDAT groups get selected depending on the selection kind. 1009Because the name of the object must match the name of the COMDAT group, the 1010linkage of the global object must not be local; local symbols can get renamed 1011if a collision occurs in the symbol table. 1012 1013The combined use of COMDATS and section attributes may yield surprising results. 1014For example: 1015 1016.. code-block:: llvm 1017 1018 $foo = comdat any 1019 $bar = comdat any 1020 @g1 = global i32 42, section "sec", comdat($foo) 1021 @g2 = global i32 42, section "sec", comdat($bar) 1022 1023From the object file perspective, this requires the creation of two sections 1024with the same name. This is necessary because both globals belong to different 1025COMDAT groups and COMDATs, at the object file level, are represented by 1026sections. 1027 1028Note that certain IR constructs like global variables and functions may 1029create COMDATs in the object file in addition to any which are specified using 1030COMDAT IR. This arises when the code generator is configured to emit globals 1031in individual sections (e.g. when `-data-sections` or `-function-sections` 1032is supplied to `llc`). 1033 1034.. _namedmetadatastructure: 1035 1036Named Metadata 1037-------------- 1038 1039Named metadata is a collection of metadata. :ref:`Metadata 1040nodes <metadata>` (but not metadata strings) are the only valid 1041operands for a named metadata. 1042 1043#. Named metadata are represented as a string of characters with the 1044 metadata prefix. The rules for metadata names are the same as for 1045 identifiers, but quoted names are not allowed. ``"\xx"`` type escapes 1046 are still valid, which allows any character to be part of a name. 1047 1048Syntax:: 1049 1050 ; Some unnamed metadata nodes, which are referenced by the named metadata. 1051 !0 = !{!"zero"} 1052 !1 = !{!"one"} 1053 !2 = !{!"two"} 1054 ; A named metadata. 1055 !name = !{!0, !1, !2} 1056 1057.. _paramattrs: 1058 1059Parameter Attributes 1060-------------------- 1061 1062The return type and each parameter of a function type may have a set of 1063*parameter attributes* associated with them. Parameter attributes are 1064used to communicate additional information about the result or 1065parameters of a function. Parameter attributes are considered to be part 1066of the function, not of the function type, so functions with different 1067parameter attributes can have the same function type. 1068 1069Parameter attributes are simple keywords that follow the type specified. 1070If multiple parameter attributes are needed, they are space separated. 1071For example: 1072 1073.. code-block:: llvm 1074 1075 declare i32 @printf(ptr noalias nocapture, ...) 1076 declare i32 @atoi(i8 zeroext) 1077 declare signext i8 @returns_signed_char() 1078 1079Note that any attributes for the function result (``nounwind``, 1080``readonly``) come immediately after the argument list. 1081 1082Currently, only the following parameter attributes are defined: 1083 1084``zeroext`` 1085 This indicates to the code generator that the parameter or return 1086 value should be zero-extended to the extent required by the target's 1087 ABI by the caller (for a parameter) or the callee (for a return value). 1088``signext`` 1089 This indicates to the code generator that the parameter or return 1090 value should be sign-extended to the extent required by the target's 1091 ABI (which is usually 32-bits) by the caller (for a parameter) or 1092 the callee (for a return value). 1093``inreg`` 1094 This indicates that this parameter or return value should be treated 1095 in a special target-dependent fashion while emitting code for 1096 a function call or return (usually, by putting it in a register as 1097 opposed to memory, though some targets use it to distinguish between 1098 two different kinds of registers). Use of this attribute is 1099 target-specific. 1100``byval(<ty>)`` 1101 This indicates that the pointer parameter should really be passed by 1102 value to the function. The attribute implies that a hidden copy of 1103 the pointee is made between the caller and the callee, so the callee 1104 is unable to modify the value in the caller. This attribute is only 1105 valid on LLVM pointer arguments. It is generally used to pass 1106 structs and arrays by value, but is also valid on pointers to 1107 scalars. The copy is considered to belong to the caller not the 1108 callee (for example, ``readonly`` functions should not write to 1109 ``byval`` parameters). This is not a valid attribute for return 1110 values. 1111 1112 The byval type argument indicates the in-memory value type, and 1113 must be the same as the pointee type of the argument. 1114 1115 The byval attribute also supports specifying an alignment with the 1116 align attribute. It indicates the alignment of the stack slot to 1117 form and the known alignment of the pointer specified to the call 1118 site. If the alignment is not specified, then the code generator 1119 makes a target-specific assumption. 1120 1121.. _attr_byref: 1122 1123``byref(<ty>)`` 1124 1125 The ``byref`` argument attribute allows specifying the pointee 1126 memory type of an argument. This is similar to ``byval``, but does 1127 not imply a copy is made anywhere, or that the argument is passed 1128 on the stack. This implies the pointer is dereferenceable up to 1129 the storage size of the type. 1130 1131 It is not generally permissible to introduce a write to an 1132 ``byref`` pointer. The pointer may have any address space and may 1133 be read only. 1134 1135 This is not a valid attribute for return values. 1136 1137 The alignment for an ``byref`` parameter can be explicitly 1138 specified by combining it with the ``align`` attribute, similar to 1139 ``byval``. If the alignment is not specified, then the code generator 1140 makes a target-specific assumption. 1141 1142 This is intended for representing ABI constraints, and is not 1143 intended to be inferred for optimization use. 1144 1145.. _attr_preallocated: 1146 1147``preallocated(<ty>)`` 1148 This indicates that the pointer parameter should really be passed by 1149 value to the function, and that the pointer parameter's pointee has 1150 already been initialized before the call instruction. This attribute 1151 is only valid on LLVM pointer arguments. The argument must be the value 1152 returned by the appropriate 1153 :ref:`llvm.call.preallocated.arg<int_call_preallocated_arg>` on non 1154 ``musttail`` calls, or the corresponding caller parameter in ``musttail`` 1155 calls, although it is ignored during codegen. 1156 1157 A non ``musttail`` function call with a ``preallocated`` attribute in 1158 any parameter must have a ``"preallocated"`` operand bundle. A ``musttail`` 1159 function call cannot have a ``"preallocated"`` operand bundle. 1160 1161 The preallocated attribute requires a type argument, which must be 1162 the same as the pointee type of the argument. 1163 1164 The preallocated attribute also supports specifying an alignment with the 1165 align attribute. It indicates the alignment of the stack slot to 1166 form and the known alignment of the pointer specified to the call 1167 site. If the alignment is not specified, then the code generator 1168 makes a target-specific assumption. 1169 1170.. _attr_inalloca: 1171 1172``inalloca(<ty>)`` 1173 1174 The ``inalloca`` argument attribute allows the caller to take the 1175 address of outgoing stack arguments. An ``inalloca`` argument must 1176 be a pointer to stack memory produced by an ``alloca`` instruction. 1177 The alloca, or argument allocation, must also be tagged with the 1178 inalloca keyword. Only the last argument may have the ``inalloca`` 1179 attribute, and that argument is guaranteed to be passed in memory. 1180 1181 An argument allocation may be used by a call at most once because 1182 the call may deallocate it. The ``inalloca`` attribute cannot be 1183 used in conjunction with other attributes that affect argument 1184 storage, like ``inreg``, ``nest``, ``sret``, or ``byval``. The 1185 ``inalloca`` attribute also disables LLVM's implicit lowering of 1186 large aggregate return values, which means that frontend authors 1187 must lower them with ``sret`` pointers. 1188 1189 When the call site is reached, the argument allocation must have 1190 been the most recent stack allocation that is still live, or the 1191 behavior is undefined. It is possible to allocate additional stack 1192 space after an argument allocation and before its call site, but it 1193 must be cleared off with :ref:`llvm.stackrestore 1194 <int_stackrestore>`. 1195 1196 The inalloca attribute requires a type argument, which must be the 1197 same as the pointee type of the argument. 1198 1199 See :doc:`InAlloca` for more information on how to use this 1200 attribute. 1201 1202``sret(<ty>)`` 1203 This indicates that the pointer parameter specifies the address of a 1204 structure that is the return value of the function in the source 1205 program. This pointer must be guaranteed by the caller to be valid: 1206 loads and stores to the structure may be assumed by the callee not 1207 to trap and to be properly aligned. This is not a valid attribute 1208 for return values. 1209 1210 The sret type argument specifies the in memory type, which must be 1211 the same as the pointee type of the argument. 1212 1213.. _attr_elementtype: 1214 1215``elementtype(<ty>)`` 1216 1217 The ``elementtype`` argument attribute can be used to specify a pointer 1218 element type in a way that is compatible with `opaque pointers 1219 <OpaquePointers.html>`__. 1220 1221 The ``elementtype`` attribute by itself does not carry any specific 1222 semantics. However, certain intrinsics may require this attribute to be 1223 present and assign it particular semantics. This will be documented on 1224 individual intrinsics. 1225 1226 The attribute may only be applied to pointer typed arguments of intrinsic 1227 calls. It cannot be applied to non-intrinsic calls, and cannot be applied 1228 to parameters on function declarations. For non-opaque pointers, the type 1229 passed to ``elementtype`` must match the pointer element type. 1230 1231.. _attr_align: 1232 1233``align <n>`` or ``align(<n>)`` 1234 This indicates that the pointer value or vector of pointers has the 1235 specified alignment. If applied to a vector of pointers, *all* pointers 1236 (elements) have the specified alignment. If the pointer value does not have 1237 the specified alignment, :ref:`poison value <poisonvalues>` is returned or 1238 passed instead. The ``align`` attribute should be combined with the 1239 ``noundef`` attribute to ensure a pointer is aligned, or otherwise the 1240 behavior is undefined. Note that ``align 1`` has no effect on non-byval, 1241 non-preallocated arguments. 1242 1243 Note that this attribute has additional semantics when combined with the 1244 ``byval`` or ``preallocated`` attribute, which are documented there. 1245 1246.. _noalias: 1247 1248``noalias`` 1249 This indicates that memory locations accessed via pointer values 1250 :ref:`based <pointeraliasing>` on the argument or return value are not also 1251 accessed, during the execution of the function, via pointer values not 1252 *based* on the argument or return value. This guarantee only holds for 1253 memory locations that are *modified*, by any means, during the execution of 1254 the function. The attribute on a return value also has additional semantics 1255 described below. The caller shares the responsibility with the callee for 1256 ensuring that these requirements are met. For further details, please see 1257 the discussion of the NoAlias response in :ref:`alias analysis <Must, May, 1258 or No>`. 1259 1260 Note that this definition of ``noalias`` is intentionally similar 1261 to the definition of ``restrict`` in C99 for function arguments. 1262 1263 For function return values, C99's ``restrict`` is not meaningful, 1264 while LLVM's ``noalias`` is. Furthermore, the semantics of the ``noalias`` 1265 attribute on return values are stronger than the semantics of the attribute 1266 when used on function arguments. On function return values, the ``noalias`` 1267 attribute indicates that the function acts like a system memory allocation 1268 function, returning a pointer to allocated storage disjoint from the 1269 storage for any other object accessible to the caller. 1270 1271.. _nocapture: 1272 1273``nocapture`` 1274 This indicates that the callee does not :ref:`capture <pointercapture>` the 1275 pointer. This is not a valid attribute for return values. 1276 This attribute applies only to the particular copy of the pointer passed in 1277 this argument. A caller could pass two copies of the same pointer with one 1278 being annotated nocapture and the other not, and the callee could validly 1279 capture through the non annotated parameter. 1280 1281.. code-block:: llvm 1282 1283 define void @f(ptr nocapture %a, ptr %b) { 1284 ; (capture %b) 1285 } 1286 1287 call void @f(ptr @glb, ptr @glb) ; well-defined 1288 1289``nofree`` 1290 This indicates that callee does not free the pointer argument. This is not 1291 a valid attribute for return values. 1292 1293.. _nest: 1294 1295``nest`` 1296 This indicates that the pointer parameter can be excised using the 1297 :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid 1298 attribute for return values and can only be applied to one parameter. 1299 1300``returned`` 1301 This indicates that the function always returns the argument as its return 1302 value. This is a hint to the optimizer and code generator used when 1303 generating the caller, allowing value propagation, tail call optimization, 1304 and omission of register saves and restores in some cases; it is not 1305 checked or enforced when generating the callee. The parameter and the 1306 function return type must be valid operands for the 1307 :ref:`bitcast instruction <i_bitcast>`. This is not a valid attribute for 1308 return values and can only be applied to one parameter. 1309 1310``nonnull`` 1311 This indicates that the parameter or return pointer is not null. This 1312 attribute may only be applied to pointer typed parameters. This is not 1313 checked or enforced by LLVM; if the parameter or return pointer is null, 1314 :ref:`poison value <poisonvalues>` is returned or passed instead. 1315 The ``nonnull`` attribute should be combined with the ``noundef`` attribute 1316 to ensure a pointer is not null or otherwise the behavior is undefined. 1317 1318``dereferenceable(<n>)`` 1319 This indicates that the parameter or return pointer is dereferenceable. This 1320 attribute may only be applied to pointer typed parameters. A pointer that 1321 is dereferenceable can be loaded from speculatively without a risk of 1322 trapping. The number of bytes known to be dereferenceable must be provided 1323 in parentheses. It is legal for the number of bytes to be less than the 1324 size of the pointee type. The ``nonnull`` attribute does not imply 1325 dereferenceability (consider a pointer to one element past the end of an 1326 array), however ``dereferenceable(<n>)`` does imply ``nonnull`` in 1327 ``addrspace(0)`` (which is the default address space), except if the 1328 ``null_pointer_is_valid`` function attribute is present. 1329 ``n`` should be a positive number. The pointer should be well defined, 1330 otherwise it is undefined behavior. This means ``dereferenceable(<n>)`` 1331 implies ``noundef``. 1332 1333``dereferenceable_or_null(<n>)`` 1334 This indicates that the parameter or return value isn't both 1335 non-null and non-dereferenceable (up to ``<n>`` bytes) at the same 1336 time. All non-null pointers tagged with 1337 ``dereferenceable_or_null(<n>)`` are ``dereferenceable(<n>)``. 1338 For address space 0 ``dereferenceable_or_null(<n>)`` implies that 1339 a pointer is exactly one of ``dereferenceable(<n>)`` or ``null``, 1340 and in other address spaces ``dereferenceable_or_null(<n>)`` 1341 implies that a pointer is at least one of ``dereferenceable(<n>)`` 1342 or ``null`` (i.e. it may be both ``null`` and 1343 ``dereferenceable(<n>)``). This attribute may only be applied to 1344 pointer typed parameters. 1345 1346``swiftself`` 1347 This indicates that the parameter is the self/context parameter. This is not 1348 a valid attribute for return values and can only be applied to one 1349 parameter. 1350 1351``swiftasync`` 1352 This indicates that the parameter is the asynchronous context parameter and 1353 triggers the creation of a target-specific extended frame record to store 1354 this pointer. This is not a valid attribute for return values and can only 1355 be applied to one parameter. 1356 1357``swifterror`` 1358 This attribute is motivated to model and optimize Swift error handling. It 1359 can be applied to a parameter with pointer to pointer type or a 1360 pointer-sized alloca. At the call site, the actual argument that corresponds 1361 to a ``swifterror`` parameter has to come from a ``swifterror`` alloca or 1362 the ``swifterror`` parameter of the caller. A ``swifterror`` value (either 1363 the parameter or the alloca) can only be loaded and stored from, or used as 1364 a ``swifterror`` argument. This is not a valid attribute for return values 1365 and can only be applied to one parameter. 1366 1367 These constraints allow the calling convention to optimize access to 1368 ``swifterror`` variables by associating them with a specific register at 1369 call boundaries rather than placing them in memory. Since this does change 1370 the calling convention, a function which uses the ``swifterror`` attribute 1371 on a parameter is not ABI-compatible with one which does not. 1372 1373 These constraints also allow LLVM to assume that a ``swifterror`` argument 1374 does not alias any other memory visible within a function and that a 1375 ``swifterror`` alloca passed as an argument does not escape. 1376 1377``immarg`` 1378 This indicates the parameter is required to be an immediate 1379 value. This must be a trivial immediate integer or floating-point 1380 constant. Undef or constant expressions are not valid. This is 1381 only valid on intrinsic declarations and cannot be applied to a 1382 call site or arbitrary function. 1383 1384``noundef`` 1385 This attribute applies to parameters and return values. If the value 1386 representation contains any undefined or poison bits, the behavior is 1387 undefined. Note that this does not refer to padding introduced by the 1388 type's storage representation. 1389 1390``alignstack(<n>)`` 1391 This indicates the alignment that should be considered by the backend when 1392 assigning this parameter to a stack slot during calling convention 1393 lowering. The enforcement of the specified alignment is target-dependent, 1394 as target-specific calling convention rules may override this value. This 1395 attribute serves the purpose of carrying language specific alignment 1396 information that is not mapped to base types in the backend (for example, 1397 over-alignment specification through language attributes). 1398 1399``allocalign`` 1400 The function parameter marked with this attribute is is the alignment in bytes of the 1401 newly allocated block returned by this function. The returned value must either have 1402 the specified alignment or be the null pointer. The return value MAY be more aligned 1403 than the requested alignment, but not less aligned. Invalid (e.g. non-power-of-2) 1404 alignments are permitted for the allocalign parameter, so long as the returned pointer 1405 is null. This attribute may only be applied to integer parameters. 1406 1407``allocptr`` 1408 The function parameter marked with this attribute is the pointer 1409 that will be manipulated by the allocator. For a realloc-like 1410 function the pointer will be invalidated upon success (but the 1411 same address may be returned), for a free-like function the 1412 pointer will always be invalidated. 1413 1414.. _gc: 1415 1416Garbage Collector Strategy Names 1417-------------------------------- 1418 1419Each function may specify a garbage collector strategy name, which is simply a 1420string: 1421 1422.. code-block:: llvm 1423 1424 define void @f() gc "name" { ... } 1425 1426The supported values of *name* includes those :ref:`built in to LLVM 1427<builtin-gc-strategies>` and any provided by loaded plugins. Specifying a GC 1428strategy will cause the compiler to alter its output in order to support the 1429named garbage collection algorithm. Note that LLVM itself does not contain a 1430garbage collector, this functionality is restricted to generating machine code 1431which can interoperate with a collector provided externally. 1432 1433.. _prefixdata: 1434 1435Prefix Data 1436----------- 1437 1438Prefix data is data associated with a function which the code 1439generator will emit immediately before the function's entrypoint. 1440The purpose of this feature is to allow frontends to associate 1441language-specific runtime metadata with specific functions and make it 1442available through the function pointer while still allowing the 1443function pointer to be called. 1444 1445To access the data for a given function, a program may bitcast the 1446function pointer to a pointer to the constant's type and dereference 1447index -1. This implies that the IR symbol points just past the end of 1448the prefix data. For instance, take the example of a function annotated 1449with a single ``i32``, 1450 1451.. code-block:: llvm 1452 1453 define void @f() prefix i32 123 { ... } 1454 1455The prefix data can be referenced as, 1456 1457.. code-block:: llvm 1458 1459 %a = getelementptr inbounds i32, ptr @f, i32 -1 1460 %b = load i32, ptr %a 1461 1462Prefix data is laid out as if it were an initializer for a global variable 1463of the prefix data's type. The function will be placed such that the 1464beginning of the prefix data is aligned. This means that if the size 1465of the prefix data is not a multiple of the alignment size, the 1466function's entrypoint will not be aligned. If alignment of the 1467function's entrypoint is desired, padding must be added to the prefix 1468data. 1469 1470A function may have prefix data but no body. This has similar semantics 1471to the ``available_externally`` linkage in that the data may be used by the 1472optimizers but will not be emitted in the object file. 1473 1474.. _prologuedata: 1475 1476Prologue Data 1477------------- 1478 1479The ``prologue`` attribute allows arbitrary code (encoded as bytes) to 1480be inserted prior to the function body. This can be used for enabling 1481function hot-patching and instrumentation. 1482 1483To maintain the semantics of ordinary function calls, the prologue data must 1484have a particular format. Specifically, it must begin with a sequence of 1485bytes which decode to a sequence of machine instructions, valid for the 1486module's target, which transfer control to the point immediately succeeding 1487the prologue data, without performing any other visible action. This allows 1488the inliner and other passes to reason about the semantics of the function 1489definition without needing to reason about the prologue data. Obviously this 1490makes the format of the prologue data highly target dependent. 1491 1492A trivial example of valid prologue data for the x86 architecture is ``i8 144``, 1493which encodes the ``nop`` instruction: 1494 1495.. code-block:: text 1496 1497 define void @f() prologue i8 144 { ... } 1498 1499Generally prologue data can be formed by encoding a relative branch instruction 1500which skips the metadata, as in this example of valid prologue data for the 1501x86_64 architecture, where the first two bytes encode ``jmp .+10``: 1502 1503.. code-block:: text 1504 1505 %0 = type <{ i8, i8, ptr }> 1506 1507 define void @f() prologue %0 <{ i8 235, i8 8, ptr @md}> { ... } 1508 1509A function may have prologue data but no body. This has similar semantics 1510to the ``available_externally`` linkage in that the data may be used by the 1511optimizers but will not be emitted in the object file. 1512 1513.. _personalityfn: 1514 1515Personality Function 1516-------------------- 1517 1518The ``personality`` attribute permits functions to specify what function 1519to use for exception handling. 1520 1521.. _attrgrp: 1522 1523Attribute Groups 1524---------------- 1525 1526Attribute groups are groups of attributes that are referenced by objects within 1527the IR. They are important for keeping ``.ll`` files readable, because a lot of 1528functions will use the same set of attributes. In the degenerative case of a 1529``.ll`` file that corresponds to a single ``.c`` file, the single attribute 1530group will capture the important command line flags used to build that file. 1531 1532An attribute group is a module-level object. To use an attribute group, an 1533object references the attribute group's ID (e.g. ``#37``). An object may refer 1534to more than one attribute group. In that situation, the attributes from the 1535different groups are merged. 1536 1537Here is an example of attribute groups for a function that should always be 1538inlined, has a stack alignment of 4, and which shouldn't use SSE instructions: 1539 1540.. code-block:: llvm 1541 1542 ; Target-independent attributes: 1543 attributes #0 = { alwaysinline alignstack=4 } 1544 1545 ; Target-dependent attributes: 1546 attributes #1 = { "no-sse" } 1547 1548 ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse". 1549 define void @f() #0 #1 { ... } 1550 1551.. _fnattrs: 1552 1553Function Attributes 1554------------------- 1555 1556Function attributes are set to communicate additional information about 1557a function. Function attributes are considered to be part of the 1558function, not of the function type, so functions with different function 1559attributes can have the same function type. 1560 1561Function attributes are simple keywords that follow the type specified. 1562If multiple attributes are needed, they are space separated. For 1563example: 1564 1565.. code-block:: llvm 1566 1567 define void @f() noinline { ... } 1568 define void @f() alwaysinline { ... } 1569 define void @f() alwaysinline optsize { ... } 1570 define void @f() optsize { ... } 1571 1572``alignstack(<n>)`` 1573 This attribute indicates that, when emitting the prologue and 1574 epilogue, the backend should forcibly align the stack pointer. 1575 Specify the desired alignment, which must be a power of two, in 1576 parentheses. 1577``"alloc-family"="FAMILY"`` 1578 This indicates which "family" an allocator function is part of. To avoid 1579 collisions, the family name should match the mangled name of the primary 1580 allocator function, that is "malloc" for malloc/calloc/realloc/free, 1581 "_Znwm" for ``::operator::new`` and ``::operator::delete``, and 1582 "_ZnwmSt11align_val_t" for aligned ``::operator::new`` and 1583 ``::operator::delete``. Matching malloc/realloc/free calls within a family 1584 can be optimized, but mismatched ones will be left alone. 1585``allockind("KIND")`` 1586 Describes the behavior of an allocation function. The KIND string contains comma 1587 separated entries from the following options: 1588 1589 * "alloc": the function returns a new block of memory or null. 1590 * "realloc": the function returns a new block of memory or null. If the 1591 result is non-null the memory contents from the start of the block up to 1592 the smaller of the original allocation size and the new allocation size 1593 will match that of the ``allocptr`` argument and the ``allocptr`` 1594 argument is invalidated, even if the function returns the same address. 1595 * "free": the function frees the block of memory specified by ``allocptr``. 1596 * "uninitialized": Any newly-allocated memory (either a new block from 1597 a "alloc" function or the enlarged capacity from a "realloc" function) 1598 will be uninitialized. 1599 * "zeroed": Any newly-allocated memory (either a new block from a "alloc" 1600 function or the enlarged capacity from a "realloc" function) will be 1601 zeroed. 1602 * "aligned": the function returns memory aligned according to the 1603 ``allocalign`` parameter. 1604 1605 The first three options are mutually exclusive, and the remaining options 1606 describe more details of how the function behaves. The remaining options 1607 are invalid for "free"-type functions. 1608``allocsize(<EltSizeParam>[, <NumEltsParam>])`` 1609 This attribute indicates that the annotated function will always return at 1610 least a given number of bytes (or null). Its arguments are zero-indexed 1611 parameter numbers; if one argument is provided, then it's assumed that at 1612 least ``CallSite.Args[EltSizeParam]`` bytes will be available at the 1613 returned pointer. If two are provided, then it's assumed that 1614 ``CallSite.Args[EltSizeParam] * CallSite.Args[NumEltsParam]`` bytes are 1615 available. The referenced parameters must be integer types. No assumptions 1616 are made about the contents of the returned block of memory. 1617``alwaysinline`` 1618 This attribute indicates that the inliner should attempt to inline 1619 this function into callers whenever possible, ignoring any active 1620 inlining size threshold for this caller. 1621``builtin`` 1622 This indicates that the callee function at a call site should be 1623 recognized as a built-in function, even though the function's declaration 1624 uses the ``nobuiltin`` attribute. This is only valid at call sites for 1625 direct calls to functions that are declared with the ``nobuiltin`` 1626 attribute. 1627``cold`` 1628 This attribute indicates that this function is rarely called. When 1629 computing edge weights, basic blocks post-dominated by a cold 1630 function call are also considered to be cold; and, thus, given low 1631 weight. 1632``convergent`` 1633 In some parallel execution models, there exist operations that cannot be 1634 made control-dependent on any additional values. We call such operations 1635 ``convergent``, and mark them with this attribute. 1636 1637 The ``convergent`` attribute may appear on functions or call/invoke 1638 instructions. When it appears on a function, it indicates that calls to 1639 this function should not be made control-dependent on additional values. 1640 For example, the intrinsic ``llvm.nvvm.barrier0`` is ``convergent``, so 1641 calls to this intrinsic cannot be made control-dependent on additional 1642 values. 1643 1644 When it appears on a call/invoke, the ``convergent`` attribute indicates 1645 that we should treat the call as though we're calling a convergent 1646 function. This is particularly useful on indirect calls; without this we 1647 may treat such calls as though the target is non-convergent. 1648 1649 The optimizer may remove the ``convergent`` attribute on functions when it 1650 can prove that the function does not execute any convergent operations. 1651 Similarly, the optimizer may remove ``convergent`` on calls/invokes when it 1652 can prove that the call/invoke cannot call a convergent function. 1653``disable_sanitizer_instrumentation`` 1654 When instrumenting code with sanitizers, it can be important to skip certain 1655 functions to ensure no instrumentation is applied to them. 1656 1657 This attribute is not always similar to absent ``sanitize_<name>`` 1658 attributes: depending on the specific sanitizer, code can be inserted into 1659 functions regardless of the ``sanitize_<name>`` attribute to prevent false 1660 positive reports. 1661 1662 ``disable_sanitizer_instrumentation`` disables all kinds of instrumentation, 1663 taking precedence over the ``sanitize_<name>`` attributes and other compiler 1664 flags. 1665``"dontcall-error"`` 1666 This attribute denotes that an error diagnostic should be emitted when a 1667 call of a function with this attribute is not eliminated via optimization. 1668 Front ends can provide optional ``srcloc`` metadata nodes on call sites of 1669 such callees to attach information about where in the source language such a 1670 call came from. A string value can be provided as a note. 1671``"dontcall-warn"`` 1672 This attribute denotes that a warning diagnostic should be emitted when a 1673 call of a function with this attribute is not eliminated via optimization. 1674 Front ends can provide optional ``srcloc`` metadata nodes on call sites of 1675 such callees to attach information about where in the source language such a 1676 call came from. A string value can be provided as a note. 1677``fn_ret_thunk_extern`` 1678 This attribute tells the code generator that returns from functions should 1679 be replaced with jumps to externally-defined architecture-specific symbols. 1680 For X86, this symbol's identifier is ``__x86_return_thunk``. 1681``"frame-pointer"`` 1682 This attribute tells the code generator whether the function 1683 should keep the frame pointer. The code generator may emit the frame pointer 1684 even if this attribute says the frame pointer can be eliminated. 1685 The allowed string values are: 1686 1687 * ``"none"`` (default) - the frame pointer can be eliminated. 1688 * ``"non-leaf"`` - the frame pointer should be kept if the function calls 1689 other functions. 1690 * ``"all"`` - the frame pointer should be kept. 1691``hot`` 1692 This attribute indicates that this function is a hot spot of the program 1693 execution. The function will be optimized more aggressively and will be 1694 placed into special subsection of the text section to improving locality. 1695 1696 When profile feedback is enabled, this attribute has the precedence over 1697 the profile information. By marking a function ``hot``, users can work 1698 around the cases where the training input does not have good coverage 1699 on all the hot functions. 1700``inaccessiblememonly`` 1701 This attribute indicates that the function may only access memory that 1702 is not accessible by the module being compiled before return from the 1703 function. This is a weaker form of ``readnone``. If the function reads 1704 or writes other memory, the behavior is undefined. 1705 1706 For clarity, note that such functions are allowed to return new memory 1707 which is ``noalias`` with respect to memory already accessible from 1708 the module. That is, a function can be both ``inaccessiblememonly`` and 1709 have a ``noalias`` return which introduces a new, potentially initialized, 1710 allocation. 1711``inaccessiblemem_or_argmemonly`` 1712 This attribute indicates that the function may only access memory that is 1713 either not accessible by the module being compiled, or is pointed to 1714 by its pointer arguments. This is a weaker form of ``argmemonly``. If the 1715 function reads or writes other memory, the behavior is undefined. 1716``inlinehint`` 1717 This attribute indicates that the source code contained a hint that 1718 inlining this function is desirable (such as the "inline" keyword in 1719 C/C++). It is just a hint; it imposes no requirements on the 1720 inliner. 1721``jumptable`` 1722 This attribute indicates that the function should be added to a 1723 jump-instruction table at code-generation time, and that all address-taken 1724 references to this function should be replaced with a reference to the 1725 appropriate jump-instruction-table function pointer. Note that this creates 1726 a new pointer for the original function, which means that code that depends 1727 on function-pointer identity can break. So, any function annotated with 1728 ``jumptable`` must also be ``unnamed_addr``. 1729``minsize`` 1730 This attribute suggests that optimization passes and code generator 1731 passes make choices that keep the code size of this function as small 1732 as possible and perform optimizations that may sacrifice runtime 1733 performance in order to minimize the size of the generated code. 1734``naked`` 1735 This attribute disables prologue / epilogue emission for the 1736 function. This can have very system-specific consequences. 1737``"no-inline-line-tables"`` 1738 When this attribute is set to true, the inliner discards source locations 1739 when inlining code and instead uses the source location of the call site. 1740 Breakpoints set on code that was inlined into the current function will 1741 not fire during the execution of the inlined call sites. If the debugger 1742 stops inside an inlined call site, it will appear to be stopped at the 1743 outermost inlined call site. 1744``no-jump-tables`` 1745 When this attribute is set to true, the jump tables and lookup tables that 1746 can be generated from a switch case lowering are disabled. 1747``nobuiltin`` 1748 This indicates that the callee function at a call site is not recognized as 1749 a built-in function. LLVM will retain the original call and not replace it 1750 with equivalent code based on the semantics of the built-in function, unless 1751 the call site uses the ``builtin`` attribute. This is valid at call sites 1752 and on function declarations and definitions. 1753``noduplicate`` 1754 This attribute indicates that calls to the function cannot be 1755 duplicated. A call to a ``noduplicate`` function may be moved 1756 within its parent function, but may not be duplicated within 1757 its parent function. 1758 1759 A function containing a ``noduplicate`` call may still 1760 be an inlining candidate, provided that the call is not 1761 duplicated by inlining. That implies that the function has 1762 internal linkage and only has one call site, so the original 1763 call is dead after inlining. 1764``nofree`` 1765 This function attribute indicates that the function does not, directly or 1766 transitively, call a memory-deallocation function (``free``, for example) 1767 on a memory allocation which existed before the call. 1768 1769 As a result, uncaptured pointers that are known to be dereferenceable 1770 prior to a call to a function with the ``nofree`` attribute are still 1771 known to be dereferenceable after the call. The capturing condition is 1772 necessary in environments where the function might communicate the 1773 pointer to another thread which then deallocates the memory. Alternatively, 1774 ``nosync`` would ensure such communication cannot happen and even captured 1775 pointers cannot be freed by the function. 1776 1777 A ``nofree`` function is explicitly allowed to free memory which it 1778 allocated or (if not ``nosync``) arrange for another thread to free 1779 memory on it's behalf. As a result, perhaps surprisingly, a ``nofree`` 1780 function can return a pointer to a previously deallocated memory object. 1781``noimplicitfloat`` 1782 Disallows implicit floating-point code. This inhibits optimizations that 1783 use floating-point code and floating-point/SIMD/vector registers for 1784 operations that are not nominally floating-point. LLVM instructions that 1785 perform floating-point operations or require access to floating-point 1786 registers may still cause floating-point code to be generated. 1787``noinline`` 1788 This attribute indicates that the inliner should never inline this 1789 function in any situation. This attribute may not be used together 1790 with the ``alwaysinline`` attribute. 1791``nomerge`` 1792 This attribute indicates that calls to this function should never be merged 1793 during optimization. For example, it will prevent tail merging otherwise 1794 identical code sequences that raise an exception or terminate the program. 1795 Tail merging normally reduces the precision of source location information, 1796 making stack traces less useful for debugging. This attribute gives the 1797 user control over the tradeoff between code size and debug information 1798 precision. 1799``nonlazybind`` 1800 This attribute suppresses lazy symbol binding for the function. This 1801 may make calls to the function faster, at the cost of extra program 1802 startup time if the function is not called during program startup. 1803``noprofile`` 1804 This function attribute prevents instrumentation based profiling, used for 1805 coverage or profile based optimization, from being added to a function, 1806 even when inlined. 1807``noredzone`` 1808 This attribute indicates that the code generator should not use a 1809 red zone, even if the target-specific ABI normally permits it. 1810``indirect-tls-seg-refs`` 1811 This attribute indicates that the code generator should not use 1812 direct TLS access through segment registers, even if the 1813 target-specific ABI normally permits it. 1814``noreturn`` 1815 This function attribute indicates that the function never returns 1816 normally, hence through a return instruction. This produces undefined 1817 behavior at runtime if the function ever does dynamically return. Annotated 1818 functions may still raise an exception, i.a., ``nounwind`` is not implied. 1819``norecurse`` 1820 This function attribute indicates that the function does not call itself 1821 either directly or indirectly down any possible call path. This produces 1822 undefined behavior at runtime if the function ever does recurse. 1823 1824.. _langref_willreturn: 1825 1826``willreturn`` 1827 This function attribute indicates that a call of this function will 1828 either exhibit undefined behavior or comes back and continues execution 1829 at a point in the existing call stack that includes the current invocation. 1830 Annotated functions may still raise an exception, i.a., ``nounwind`` is not implied. 1831 If an invocation of an annotated function does not return control back 1832 to a point in the call stack, the behavior is undefined. 1833``nosync`` 1834 This function attribute indicates that the function does not communicate 1835 (synchronize) with another thread through memory or other well-defined means. 1836 Synchronization is considered possible in the presence of `atomic` accesses 1837 that enforce an order, thus not "unordered" and "monotonic", `volatile` accesses, 1838 as well as `convergent` function calls. Note that through `convergent` function calls 1839 non-memory communication, e.g., cross-lane operations, are possible and are also 1840 considered synchronization. However `convergent` does not contradict `nosync`. 1841 If an annotated function does ever synchronize with another thread, 1842 the behavior is undefined. 1843``nounwind`` 1844 This function attribute indicates that the function never raises an 1845 exception. If the function does raise an exception, its runtime 1846 behavior is undefined. However, functions marked nounwind may still 1847 trap or generate asynchronous exceptions. Exception handling schemes 1848 that are recognized by LLVM to handle asynchronous exceptions, such 1849 as SEH, will still provide their implementation defined semantics. 1850``nosanitize_bounds`` 1851 This attribute indicates that bounds checking sanitizer instrumentation 1852 is disabled for this function. 1853``nosanitize_coverage`` 1854 This attribute indicates that SanitizerCoverage instrumentation is disabled 1855 for this function. 1856``null_pointer_is_valid`` 1857 If ``null_pointer_is_valid`` is set, then the ``null`` address 1858 in address-space 0 is considered to be a valid address for memory loads and 1859 stores. Any analysis or optimization should not treat dereferencing a 1860 pointer to ``null`` as undefined behavior in this function. 1861 Note: Comparing address of a global variable to ``null`` may still 1862 evaluate to false because of a limitation in querying this attribute inside 1863 constant expressions. 1864``optforfuzzing`` 1865 This attribute indicates that this function should be optimized 1866 for maximum fuzzing signal. 1867``optnone`` 1868 This function attribute indicates that most optimization passes will skip 1869 this function, with the exception of interprocedural optimization passes. 1870 Code generation defaults to the "fast" instruction selector. 1871 This attribute cannot be used together with the ``alwaysinline`` 1872 attribute; this attribute is also incompatible 1873 with the ``minsize`` attribute and the ``optsize`` attribute. 1874 1875 This attribute requires the ``noinline`` attribute to be specified on 1876 the function as well, so the function is never inlined into any caller. 1877 Only functions with the ``alwaysinline`` attribute are valid 1878 candidates for inlining into the body of this function. 1879``optsize`` 1880 This attribute suggests that optimization passes and code generator 1881 passes make choices that keep the code size of this function low, 1882 and otherwise do optimizations specifically to reduce code size as 1883 long as they do not significantly impact runtime performance. 1884``"patchable-function"`` 1885 This attribute tells the code generator that the code 1886 generated for this function needs to follow certain conventions that 1887 make it possible for a runtime function to patch over it later. 1888 The exact effect of this attribute depends on its string value, 1889 for which there currently is one legal possibility: 1890 1891 * ``"prologue-short-redirect"`` - This style of patchable 1892 function is intended to support patching a function prologue to 1893 redirect control away from the function in a thread safe 1894 manner. It guarantees that the first instruction of the 1895 function will be large enough to accommodate a short jump 1896 instruction, and will be sufficiently aligned to allow being 1897 fully changed via an atomic compare-and-swap instruction. 1898 While the first requirement can be satisfied by inserting large 1899 enough NOP, LLVM can and will try to re-purpose an existing 1900 instruction (i.e. one that would have to be emitted anyway) as 1901 the patchable instruction larger than a short jump. 1902 1903 ``"prologue-short-redirect"`` is currently only supported on 1904 x86-64. 1905 1906 This attribute by itself does not imply restrictions on 1907 inter-procedural optimizations. All of the semantic effects the 1908 patching may have to be separately conveyed via the linkage type. 1909``"probe-stack"`` 1910 This attribute indicates that the function will trigger a guard region 1911 in the end of the stack. It ensures that accesses to the stack must be 1912 no further apart than the size of the guard region to a previous 1913 access of the stack. It takes one required string value, the name of 1914 the stack probing function that will be called. 1915 1916 If a function that has a ``"probe-stack"`` attribute is inlined into 1917 a function with another ``"probe-stack"`` attribute, the resulting 1918 function has the ``"probe-stack"`` attribute of the caller. If a 1919 function that has a ``"probe-stack"`` attribute is inlined into a 1920 function that has no ``"probe-stack"`` attribute at all, the resulting 1921 function has the ``"probe-stack"`` attribute of the callee. 1922``readnone`` 1923 On a function, this attribute indicates that the function computes its 1924 result (or decides to unwind an exception) based strictly on its arguments, 1925 without dereferencing any pointer arguments or otherwise accessing 1926 any mutable state (e.g. memory, control registers, etc) visible outside the 1927 ``readnone`` function. It does not write through any pointer arguments 1928 (including ``byval`` arguments) and never changes any state visible to 1929 callers. This means while it cannot unwind exceptions by calling the ``C++`` 1930 exception throwing methods (since they write to memory), there may be 1931 non-``C++`` mechanisms that throw exceptions without writing to LLVM visible 1932 memory. 1933 1934 On an argument, this attribute indicates that the function does not 1935 dereference that pointer argument, even though it may read or write the 1936 memory that the pointer points to if accessed through other pointers. 1937 1938 If a readnone function reads or writes memory visible outside the function, 1939 or has other side-effects, the behavior is undefined. If a 1940 function reads from or writes to a readnone pointer argument, the behavior 1941 is undefined. 1942``readonly`` 1943 On a function, this attribute indicates that the function does not write 1944 through any pointer arguments (including ``byval`` arguments) or otherwise 1945 modify any state (e.g. memory, control registers, etc) visible outside the 1946 ``readonly`` function. It may dereference pointer arguments and read 1947 state that may be set in the caller. A readonly function always 1948 returns the same value (or unwinds an exception identically) when 1949 called with the same set of arguments and global state. This means while it 1950 cannot unwind exceptions by calling the ``C++`` exception throwing methods 1951 (since they write to memory), there may be non-``C++`` mechanisms that throw 1952 exceptions without writing to LLVM visible memory. 1953 1954 On an argument, this attribute indicates that the function does not write 1955 through this pointer argument, even though it may write to the memory that 1956 the pointer points to. 1957 1958 If a readonly function writes memory visible outside the function, or has 1959 other side-effects, the behavior is undefined. If a function writes to a 1960 readonly pointer argument, the behavior is undefined. 1961``"stack-probe-size"`` 1962 This attribute controls the behavior of stack probes: either 1963 the ``"probe-stack"`` attribute, or ABI-required stack probes, if any. 1964 It defines the size of the guard region. It ensures that if the function 1965 may use more stack space than the size of the guard region, stack probing 1966 sequence will be emitted. It takes one required integer value, which 1967 is 4096 by default. 1968 1969 If a function that has a ``"stack-probe-size"`` attribute is inlined into 1970 a function with another ``"stack-probe-size"`` attribute, the resulting 1971 function has the ``"stack-probe-size"`` attribute that has the lower 1972 numeric value. If a function that has a ``"stack-probe-size"`` attribute is 1973 inlined into a function that has no ``"stack-probe-size"`` attribute 1974 at all, the resulting function has the ``"stack-probe-size"`` attribute 1975 of the callee. 1976``"no-stack-arg-probe"`` 1977 This attribute disables ABI-required stack probes, if any. 1978``writeonly`` 1979 On a function, this attribute indicates that the function may write to but 1980 does not read from memory visible outside the ``writeonly`` function. 1981 1982 On an argument, this attribute indicates that the function may write to but 1983 does not read through this pointer argument (even though it may read from 1984 the memory that the pointer points to). 1985 1986 If a writeonly function reads memory visible outside the function or has 1987 other side-effects, the behavior is undefined. If a function reads 1988 from a writeonly pointer argument, the behavior is undefined. 1989``argmemonly`` 1990 This attribute indicates that the only memory accesses inside function are 1991 loads and stores from objects pointed to by its pointer-typed arguments, 1992 with arbitrary offsets. Or in other words, all memory operations in the 1993 function can refer to memory only using pointers based on its function 1994 arguments. 1995 1996 Note that ``argmemonly`` can be used together with ``readonly`` attribute 1997 in order to specify that function reads only from its arguments. 1998 1999 If an argmemonly function reads or writes memory other than the pointer 2000 arguments, or has other side-effects, the behavior is undefined. 2001``returns_twice`` 2002 This attribute indicates that this function can return twice. The C 2003 ``setjmp`` is an example of such a function. The compiler disables 2004 some optimizations (like tail calls) in the caller of these 2005 functions. 2006``safestack`` 2007 This attribute indicates that 2008 `SafeStack <https://clang.llvm.org/docs/SafeStack.html>`_ 2009 protection is enabled for this function. 2010 2011 If a function that has a ``safestack`` attribute is inlined into a 2012 function that doesn't have a ``safestack`` attribute or which has an 2013 ``ssp``, ``sspstrong`` or ``sspreq`` attribute, then the resulting 2014 function will have a ``safestack`` attribute. 2015``sanitize_address`` 2016 This attribute indicates that AddressSanitizer checks 2017 (dynamic address safety analysis) are enabled for this function. 2018``sanitize_memory`` 2019 This attribute indicates that MemorySanitizer checks (dynamic detection 2020 of accesses to uninitialized memory) are enabled for this function. 2021``sanitize_thread`` 2022 This attribute indicates that ThreadSanitizer checks 2023 (dynamic thread safety analysis) are enabled for this function. 2024``sanitize_hwaddress`` 2025 This attribute indicates that HWAddressSanitizer checks 2026 (dynamic address safety analysis based on tagged pointers) are enabled for 2027 this function. 2028``sanitize_memtag`` 2029 This attribute indicates that MemTagSanitizer checks 2030 (dynamic address safety analysis based on Armv8 MTE) are enabled for 2031 this function. 2032``speculative_load_hardening`` 2033 This attribute indicates that 2034 `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_ 2035 should be enabled for the function body. 2036 2037 Speculative Load Hardening is a best-effort mitigation against 2038 information leak attacks that make use of control flow 2039 miss-speculation - specifically miss-speculation of whether a branch 2040 is taken or not. Typically vulnerabilities enabling such attacks are 2041 classified as "Spectre variant #1". Notably, this does not attempt to 2042 mitigate against miss-speculation of branch target, classified as 2043 "Spectre variant #2" vulnerabilities. 2044 2045 When inlining, the attribute is sticky. Inlining a function that carries 2046 this attribute will cause the caller to gain the attribute. This is intended 2047 to provide a maximally conservative model where the code in a function 2048 annotated with this attribute will always (even after inlining) end up 2049 hardened. 2050``speculatable`` 2051 This function attribute indicates that the function does not have any 2052 effects besides calculating its result and does not have undefined behavior. 2053 Note that ``speculatable`` is not enough to conclude that along any 2054 particular execution path the number of calls to this function will not be 2055 externally observable. This attribute is only valid on functions 2056 and declarations, not on individual call sites. If a function is 2057 incorrectly marked as speculatable and really does exhibit 2058 undefined behavior, the undefined behavior may be observed even 2059 if the call site is dead code. 2060 2061``ssp`` 2062 This attribute indicates that the function should emit a stack 2063 smashing protector. It is in the form of a "canary" --- a random value 2064 placed on the stack before the local variables that's checked upon 2065 return from the function to see if it has been overwritten. A 2066 heuristic is used to determine if a function needs stack protectors 2067 or not. The heuristic used will enable protectors for functions with: 2068 2069 - Character arrays larger than ``ssp-buffer-size`` (default 8). 2070 - Aggregates containing character arrays larger than ``ssp-buffer-size``. 2071 - Calls to alloca() with variable sizes or constant sizes greater than 2072 ``ssp-buffer-size``. 2073 2074 Variables that are identified as requiring a protector will be arranged 2075 on the stack such that they are adjacent to the stack protector guard. 2076 2077 If a function with an ``ssp`` attribute is inlined into a calling function, 2078 the attribute is not carried over to the calling function. 2079 2080``sspstrong`` 2081 This attribute indicates that the function should emit a stack smashing 2082 protector. This attribute causes a strong heuristic to be used when 2083 determining if a function needs stack protectors. The strong heuristic 2084 will enable protectors for functions with: 2085 2086 - Arrays of any size and type 2087 - Aggregates containing an array of any size and type. 2088 - Calls to alloca(). 2089 - Local variables that have had their address taken. 2090 2091 Variables that are identified as requiring a protector will be arranged 2092 on the stack such that they are adjacent to the stack protector guard. 2093 The specific layout rules are: 2094 2095 #. Large arrays and structures containing large arrays 2096 (``>= ssp-buffer-size``) are closest to the stack protector. 2097 #. Small arrays and structures containing small arrays 2098 (``< ssp-buffer-size``) are 2nd closest to the protector. 2099 #. Variables that have had their address taken are 3rd closest to the 2100 protector. 2101 2102 This overrides the ``ssp`` function attribute. 2103 2104 If a function with an ``sspstrong`` attribute is inlined into a calling 2105 function which has an ``ssp`` attribute, the calling function's attribute 2106 will be upgraded to ``sspstrong``. 2107 2108``sspreq`` 2109 This attribute indicates that the function should *always* emit a stack 2110 smashing protector. This overrides the ``ssp`` and ``sspstrong`` function 2111 attributes. 2112 2113 Variables that are identified as requiring a protector will be arranged 2114 on the stack such that they are adjacent to the stack protector guard. 2115 The specific layout rules are: 2116 2117 #. Large arrays and structures containing large arrays 2118 (``>= ssp-buffer-size``) are closest to the stack protector. 2119 #. Small arrays and structures containing small arrays 2120 (``< ssp-buffer-size``) are 2nd closest to the protector. 2121 #. Variables that have had their address taken are 3rd closest to the 2122 protector. 2123 2124 If a function with an ``sspreq`` attribute is inlined into a calling 2125 function which has an ``ssp`` or ``sspstrong`` attribute, the calling 2126 function's attribute will be upgraded to ``sspreq``. 2127 2128``strictfp`` 2129 This attribute indicates that the function was called from a scope that 2130 requires strict floating-point semantics. LLVM will not attempt any 2131 optimizations that require assumptions about the floating-point rounding 2132 mode or that might alter the state of floating-point status flags that 2133 might otherwise be set or cleared by calling this function. LLVM will 2134 not introduce any new floating-point instructions that may trap. 2135 2136``"denormal-fp-math"`` 2137 This indicates the denormal (subnormal) handling that may be 2138 assumed for the default floating-point environment. This is a 2139 comma separated pair. The elements may be one of ``"ieee"``, 2140 ``"preserve-sign"``, or ``"positive-zero"``. The first entry 2141 indicates the flushing mode for the result of floating point 2142 operations. The second indicates the handling of denormal inputs 2143 to floating point instructions. For compatibility with older 2144 bitcode, if the second value is omitted, both input and output 2145 modes will assume the same mode. 2146 2147 If this is attribute is not specified, the default is 2148 ``"ieee,ieee"``. 2149 2150 If the output mode is ``"preserve-sign"``, or ``"positive-zero"``, 2151 denormal outputs may be flushed to zero by standard floating-point 2152 operations. It is not mandated that flushing to zero occurs, but if 2153 a denormal output is flushed to zero, it must respect the sign 2154 mode. Not all targets support all modes. While this indicates the 2155 expected floating point mode the function will be executed with, 2156 this does not make any attempt to ensure the mode is 2157 consistent. User or platform code is expected to set the floating 2158 point mode appropriately before function entry. 2159 2160 If the input mode is ``"preserve-sign"``, or ``"positive-zero"``, a 2161 floating-point operation must treat any input denormal value as 2162 zero. In some situations, if an instruction does not respect this 2163 mode, the input may need to be converted to 0 as if by 2164 ``@llvm.canonicalize`` during lowering for correctness. 2165 2166``"denormal-fp-math-f32"`` 2167 Same as ``"denormal-fp-math"``, but only controls the behavior of 2168 the 32-bit float type (or vectors of 32-bit floats). If both are 2169 are present, this overrides ``"denormal-fp-math"``. Not all targets 2170 support separately setting the denormal mode per type, and no 2171 attempt is made to diagnose unsupported uses. Currently this 2172 attribute is respected by the AMDGPU and NVPTX backends. 2173 2174``"thunk"`` 2175 This attribute indicates that the function will delegate to some other 2176 function with a tail call. The prototype of a thunk should not be used for 2177 optimization purposes. The caller is expected to cast the thunk prototype to 2178 match the thunk target prototype. 2179 2180``"tls-load-hoist"`` 2181 This attribute indicates that the function will try to reduce redundant 2182 tls address calculation by hoisting tls variable. 2183 2184``uwtable[(sync|async)]`` 2185 This attribute indicates that the ABI being targeted requires that 2186 an unwind table entry be produced for this function even if we can 2187 show that no exceptions passes by it. This is normally the case for 2188 the ELF x86-64 abi, but it can be disabled for some compilation 2189 units. The optional parameter describes what kind of unwind tables 2190 to generate: ``sync`` for normal unwind tables, ``async`` for asynchronous 2191 (instruction precise) unwind tables. Without the parameter, the attribute 2192 ``uwtable`` is equivalent to ``uwtable(async)``. 2193``nocf_check`` 2194 This attribute indicates that no control-flow check will be performed on 2195 the attributed entity. It disables -fcf-protection=<> for a specific 2196 entity to fine grain the HW control flow protection mechanism. The flag 2197 is target independent and currently appertains to a function or function 2198 pointer. 2199``shadowcallstack`` 2200 This attribute indicates that the ShadowCallStack checks are enabled for 2201 the function. The instrumentation checks that the return address for the 2202 function has not changed between the function prolog and epilog. It is 2203 currently x86_64-specific. 2204 2205.. _langref_mustprogress: 2206 2207``mustprogress`` 2208 This attribute indicates that the function is required to return, unwind, 2209 or interact with the environment in an observable way e.g. via a volatile 2210 memory access, I/O, or other synchronization. The ``mustprogress`` 2211 attribute is intended to model the requirements of the first section of 2212 [intro.progress] of the C++ Standard. As a consequence, a loop in a 2213 function with the `mustprogress` attribute can be assumed to terminate if 2214 it does not interact with the environment in an observable way, and 2215 terminating loops without side-effects can be removed. If a `mustprogress` 2216 function does not satisfy this contract, the behavior is undefined. This 2217 attribute does not apply transitively to callees, but does apply to call 2218 sites within the function. Note that `willreturn` implies `mustprogress`. 2219``"warn-stack-size"="<threshold>"`` 2220 This attribute sets a threshold to emit diagnostics once the frame size is 2221 known should the frame size exceed the specified value. It takes one 2222 required integer value, which should be a non-negative integer, and less 2223 than `UINT_MAX`. It's unspecified which threshold will be used when 2224 duplicate definitions are linked together with differing values. 2225``vscale_range(<min>[, <max>])`` 2226 This attribute indicates the minimum and maximum vscale value for the given 2227 function. The min must be greater than 0. A maximum value of 0 means 2228 unbounded. If the optional max value is omitted then max is set to the 2229 value of min. If the attribute is not present, no assumptions are made 2230 about the range of vscale. 2231``"min-legal-vector-width"="<size>"`` 2232 This attribute indicates the minimum legal vector width required by the 2233 calling conversion. It is the maximum width of vector arguments and 2234 returnings in the function and functions called by this function. Because 2235 all the vectors are supposed to be legal type for compatibility. 2236 Backends are free to ignore the attribute if they don't need to support 2237 different maximum legal vector types or such information can be inferred by 2238 other attributes. 2239 2240Call Site Attributes 2241---------------------- 2242 2243In addition to function attributes the following call site only 2244attributes are supported: 2245 2246``vector-function-abi-variant`` 2247 This attribute can be attached to a :ref:`call <i_call>` to list 2248 the vector functions associated to the function. Notice that the 2249 attribute cannot be attached to a :ref:`invoke <i_invoke>` or a 2250 :ref:`callbr <i_callbr>` instruction. The attribute consists of a 2251 comma separated list of mangled names. The order of the list does 2252 not imply preference (it is logically a set). The compiler is free 2253 to pick any listed vector function of its choosing. 2254 2255 The syntax for the mangled names is as follows::: 2256 2257 _ZGV<isa><mask><vlen><parameters>_<scalar_name>[(<vector_redirection>)] 2258 2259 When present, the attribute informs the compiler that the function 2260 ``<scalar_name>`` has a corresponding vector variant that can be 2261 used to perform the concurrent invocation of ``<scalar_name>`` on 2262 vectors. The shape of the vector function is described by the 2263 tokens between the prefix ``_ZGV`` and the ``<scalar_name>`` 2264 token. The standard name of the vector function is 2265 ``_ZGV<isa><mask><vlen><parameters>_<scalar_name>``. When present, 2266 the optional token ``(<vector_redirection>)`` informs the compiler 2267 that a custom name is provided in addition to the standard one 2268 (custom names can be provided for example via the use of ``declare 2269 variant`` in OpenMP 5.0). The declaration of the variant must be 2270 present in the IR Module. The signature of the vector variant is 2271 determined by the rules of the Vector Function ABI (VFABI) 2272 specifications of the target. For Arm and X86, the VFABI can be 2273 found at https://github.com/ARM-software/abi-aa and 2274 https://software.intel.com/content/www/us/en/develop/download/vector-simd-function-abi.html, 2275 respectively. 2276 2277 For X86 and Arm targets, the values of the tokens in the standard 2278 name are those that are defined in the VFABI. LLVM has an internal 2279 ``<isa>`` token that can be used to create scalar-to-vector 2280 mappings for functions that are not directly associated to any of 2281 the target ISAs (for example, some of the mappings stored in the 2282 TargetLibraryInfo). Valid values for the ``<isa>`` token are::: 2283 2284 <isa>:= b | c | d | e -> X86 SSE, AVX, AVX2, AVX512 2285 | n | s -> Armv8 Advanced SIMD, SVE 2286 | __LLVM__ -> Internal LLVM Vector ISA 2287 2288 For all targets currently supported (x86, Arm and Internal LLVM), 2289 the remaining tokens can have the following values::: 2290 2291 <mask>:= M | N -> mask | no mask 2292 2293 <vlen>:= number -> number of lanes 2294 | x -> VLA (Vector Length Agnostic) 2295 2296 <parameters>:= v -> vector 2297 | l | l <number> -> linear 2298 | R | R <number> -> linear with ref modifier 2299 | L | L <number> -> linear with val modifier 2300 | U | U <number> -> linear with uval modifier 2301 | ls <pos> -> runtime linear 2302 | Rs <pos> -> runtime linear with ref modifier 2303 | Ls <pos> -> runtime linear with val modifier 2304 | Us <pos> -> runtime linear with uval modifier 2305 | u -> uniform 2306 2307 <scalar_name>:= name of the scalar function 2308 2309 <vector_redirection>:= optional, custom name of the vector function 2310 2311``preallocated(<ty>)`` 2312 This attribute is required on calls to ``llvm.call.preallocated.arg`` 2313 and cannot be used on any other call. See 2314 :ref:`llvm.call.preallocated.arg<int_call_preallocated_arg>` for more 2315 details. 2316 2317.. _glattrs: 2318 2319Global Attributes 2320----------------- 2321 2322Attributes may be set to communicate additional information about a global variable. 2323Unlike :ref:`function attributes <fnattrs>`, attributes on a global variable 2324are grouped into a single :ref:`attribute group <attrgrp>`. 2325 2326``no_sanitize_address`` 2327 This attribute indicates that the global variable should not have 2328 AddressSanitizer instrumentation applied to it, because it was annotated 2329 with `__attribute__((no_sanitize("address")))`, 2330 `__attribute__((disable_sanitizer_instrumentation))`, or included in the 2331 `-fsanitize-ignorelist` file. 2332``no_sanitize_hwaddress`` 2333 This attribute indicates that the global variable should not have 2334 HWAddressSanitizer instrumentation applied to it, because it was annotated 2335 with `__attribute__((no_sanitize("hwaddress")))`, 2336 `__attribute__((disable_sanitizer_instrumentation))`, or included in the 2337 `-fsanitize-ignorelist` file. 2338``sanitize_memtag`` 2339 This attribute indicates that the global variable should have AArch64 memory 2340 tags (MTE) instrumentation applied to it. This attribute causes the 2341 suppression of certain optimisations, like GlobalMerge, as well as ensuring 2342 extra directives are emitted in the assembly and extra bits of metadata are 2343 placed in the object file so that the linker can ensure the accesses are 2344 protected by MTE. This attribute is added by clang when 2345 `-fsanitize=memtag-globals` is provided, as long as the global is not marked 2346 with `__attribute__((no_sanitize("memtag")))`, 2347 `__attribute__((disable_sanitizer_instrumentation))`, or included in the 2348 `-fsanitize-ignorelist` file. The AArch64 Globals Tagging pass may remove 2349 this attribute when it's not possible to tag the global (e.g. it's a TLS 2350 variable). 2351``sanitize_address_dyninit`` 2352 This attribute indicates that the global variable, when instrumented with 2353 AddressSanitizer, should be checked for ODR violations. This attribute is 2354 applied to global variables that are dynamically initialized according to 2355 C++ rules. 2356 2357.. _opbundles: 2358 2359Operand Bundles 2360--------------- 2361 2362Operand bundles are tagged sets of SSA values that can be associated 2363with certain LLVM instructions (currently only ``call`` s and 2364``invoke`` s). In a way they are like metadata, but dropping them is 2365incorrect and will change program semantics. 2366 2367Syntax:: 2368 2369 operand bundle set ::= '[' operand bundle (, operand bundle )* ']' 2370 operand bundle ::= tag '(' [ bundle operand ] (, bundle operand )* ')' 2371 bundle operand ::= SSA value 2372 tag ::= string constant 2373 2374Operand bundles are **not** part of a function's signature, and a 2375given function may be called from multiple places with different kinds 2376of operand bundles. This reflects the fact that the operand bundles 2377are conceptually a part of the ``call`` (or ``invoke``), not the 2378callee being dispatched to. 2379 2380Operand bundles are a generic mechanism intended to support 2381runtime-introspection-like functionality for managed languages. While 2382the exact semantics of an operand bundle depend on the bundle tag, 2383there are certain limitations to how much the presence of an operand 2384bundle can influence the semantics of a program. These restrictions 2385are described as the semantics of an "unknown" operand bundle. As 2386long as the behavior of an operand bundle is describable within these 2387restrictions, LLVM does not need to have special knowledge of the 2388operand bundle to not miscompile programs containing it. 2389 2390- The bundle operands for an unknown operand bundle escape in unknown 2391 ways before control is transferred to the callee or invokee. 2392- Calls and invokes with operand bundles have unknown read / write 2393 effect on the heap on entry and exit (even if the call target is 2394 ``readnone`` or ``readonly``), unless they're overridden with 2395 callsite specific attributes. 2396- An operand bundle at a call site cannot change the implementation 2397 of the called function. Inter-procedural optimizations work as 2398 usual as long as they take into account the first two properties. 2399 2400More specific types of operand bundles are described below. 2401 2402.. _deopt_opbundles: 2403 2404Deoptimization Operand Bundles 2405^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2406 2407Deoptimization operand bundles are characterized by the ``"deopt"`` 2408operand bundle tag. These operand bundles represent an alternate 2409"safe" continuation for the call site they're attached to, and can be 2410used by a suitable runtime to deoptimize the compiled frame at the 2411specified call site. There can be at most one ``"deopt"`` operand 2412bundle attached to a call site. Exact details of deoptimization is 2413out of scope for the language reference, but it usually involves 2414rewriting a compiled frame into a set of interpreted frames. 2415 2416From the compiler's perspective, deoptimization operand bundles make 2417the call sites they're attached to at least ``readonly``. They read 2418through all of their pointer typed operands (even if they're not 2419otherwise escaped) and the entire visible heap. Deoptimization 2420operand bundles do not capture their operands except during 2421deoptimization, in which case control will not be returned to the 2422compiled frame. 2423 2424The inliner knows how to inline through calls that have deoptimization 2425operand bundles. Just like inlining through a normal call site 2426involves composing the normal and exceptional continuations, inlining 2427through a call site with a deoptimization operand bundle needs to 2428appropriately compose the "safe" deoptimization continuation. The 2429inliner does this by prepending the parent's deoptimization 2430continuation to every deoptimization continuation in the inlined body. 2431E.g. inlining ``@f`` into ``@g`` in the following example 2432 2433.. code-block:: llvm 2434 2435 define void @f() { 2436 call void @x() ;; no deopt state 2437 call void @y() [ "deopt"(i32 10) ] 2438 call void @y() [ "deopt"(i32 10), "unknown"(ptr null) ] 2439 ret void 2440 } 2441 2442 define void @g() { 2443 call void @f() [ "deopt"(i32 20) ] 2444 ret void 2445 } 2446 2447will result in 2448 2449.. code-block:: llvm 2450 2451 define void @g() { 2452 call void @x() ;; still no deopt state 2453 call void @y() [ "deopt"(i32 20, i32 10) ] 2454 call void @y() [ "deopt"(i32 20, i32 10), "unknown"(ptr null) ] 2455 ret void 2456 } 2457 2458It is the frontend's responsibility to structure or encode the 2459deoptimization state in a way that syntactically prepending the 2460caller's deoptimization state to the callee's deoptimization state is 2461semantically equivalent to composing the caller's deoptimization 2462continuation after the callee's deoptimization continuation. 2463 2464.. _ob_funclet: 2465 2466Funclet Operand Bundles 2467^^^^^^^^^^^^^^^^^^^^^^^ 2468 2469Funclet operand bundles are characterized by the ``"funclet"`` 2470operand bundle tag. These operand bundles indicate that a call site 2471is within a particular funclet. There can be at most one 2472``"funclet"`` operand bundle attached to a call site and it must have 2473exactly one bundle operand. 2474 2475If any funclet EH pads have been "entered" but not "exited" (per the 2476`description in the EH doc\ <ExceptionHandling.html#wineh-constraints>`_), 2477it is undefined behavior to execute a ``call`` or ``invoke`` which: 2478 2479* does not have a ``"funclet"`` bundle and is not a ``call`` to a nounwind 2480 intrinsic, or 2481* has a ``"funclet"`` bundle whose operand is not the most-recently-entered 2482 not-yet-exited funclet EH pad. 2483 2484Similarly, if no funclet EH pads have been entered-but-not-yet-exited, 2485executing a ``call`` or ``invoke`` with a ``"funclet"`` bundle is undefined behavior. 2486 2487GC Transition Operand Bundles 2488^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2489 2490GC transition operand bundles are characterized by the 2491``"gc-transition"`` operand bundle tag. These operand bundles mark a 2492call as a transition between a function with one GC strategy to a 2493function with a different GC strategy. If coordinating the transition 2494between GC strategies requires additional code generation at the call 2495site, these bundles may contain any values that are needed by the 2496generated code. For more details, see :ref:`GC Transitions 2497<gc_transition_args>`. 2498 2499The bundle contain an arbitrary list of Values which need to be passed 2500to GC transition code. They will be lowered and passed as operands to 2501the appropriate GC_TRANSITION nodes in the selection DAG. It is assumed 2502that these arguments must be available before and after (but not 2503necessarily during) the execution of the callee. 2504 2505.. _assume_opbundles: 2506 2507Assume Operand Bundles 2508^^^^^^^^^^^^^^^^^^^^^^ 2509 2510Operand bundles on an :ref:`llvm.assume <int_assume>` allows representing 2511assumptions that a :ref:`parameter attribute <paramattrs>` or a 2512:ref:`function attribute <fnattrs>` holds for a certain value at a certain 2513location. Operand bundles enable assumptions that are either hard or impossible 2514to represent as a boolean argument of an :ref:`llvm.assume <int_assume>`. 2515 2516An assume operand bundle has the form: 2517 2518:: 2519 2520 "<tag>"([ <holds for value> [, <attribute argument>] ]) 2521 2522* The tag of the operand bundle is usually the name of attribute that can be 2523 assumed to hold. It can also be `ignore`, this tag doesn't contain any 2524 information and should be ignored. 2525* The first argument if present is the value for which the attribute hold. 2526* The second argument if present is an argument of the attribute. 2527 2528If there are no arguments the attribute is a property of the call location. 2529 2530For example: 2531 2532.. code-block:: llvm 2533 2534 call void @llvm.assume(i1 true) ["align"(ptr %val, i32 8)] 2535 2536allows the optimizer to assume that at location of call to 2537:ref:`llvm.assume <int_assume>` ``%val`` has an alignment of at least 8. 2538 2539.. code-block:: llvm 2540 2541 call void @llvm.assume(i1 %cond) ["cold"(), "nonnull"(ptr %val)] 2542 2543allows the optimizer to assume that the :ref:`llvm.assume <int_assume>` 2544call location is cold and that ``%val`` may not be null. 2545 2546Just like for the argument of :ref:`llvm.assume <int_assume>`, if any of the 2547provided guarantees are violated at runtime the behavior is undefined. 2548 2549While attributes expect constant arguments, assume operand bundles may be 2550provided a dynamic value, for example: 2551 2552.. code-block:: llvm 2553 2554 call void @llvm.assume(i1 true) ["align"(ptr %val, i32 %align)] 2555 2556If the operand bundle value violates any requirements on the attribute value, 2557the behavior is undefined, unless one of the following exceptions applies: 2558 2559* ``"assume"`` operand bundles may specify a non-power-of-two alignment 2560 (including a zero alignment). If this is the case, then the pointer value 2561 must be a null pointer, otherwise the behavior is undefined. 2562 2563Even if the assumed property can be encoded as a boolean value, like 2564``nonnull``, using operand bundles to express the property can still have 2565benefits: 2566 2567* Attributes that can be expressed via operand bundles are directly the 2568 property that the optimizer uses and cares about. Encoding attributes as 2569 operand bundles removes the need for an instruction sequence that represents 2570 the property (e.g., `icmp ne ptr %p, null` for `nonnull`) and for the 2571 optimizer to deduce the property from that instruction sequence. 2572* Expressing the property using operand bundles makes it easy to identify the 2573 use of the value as a use in an :ref:`llvm.assume <int_assume>`. This then 2574 simplifies and improves heuristics, e.g., for use "use-sensitive" 2575 optimizations. 2576 2577.. _ob_preallocated: 2578 2579Preallocated Operand Bundles 2580^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2581 2582Preallocated operand bundles are characterized by the ``"preallocated"`` 2583operand bundle tag. These operand bundles allow separation of the allocation 2584of the call argument memory from the call site. This is necessary to pass 2585non-trivially copyable objects by value in a way that is compatible with MSVC 2586on some targets. There can be at most one ``"preallocated"`` operand bundle 2587attached to a call site and it must have exactly one bundle operand, which is 2588a token generated by ``@llvm.call.preallocated.setup``. A call with this 2589operand bundle should not adjust the stack before entering the function, as 2590that will have been done by one of the ``@llvm.call.preallocated.*`` intrinsics. 2591 2592.. code-block:: llvm 2593 2594 %foo = type { i64, i32 } 2595 2596 ... 2597 2598 %t = call token @llvm.call.preallocated.setup(i32 1) 2599 %a = call ptr @llvm.call.preallocated.arg(token %t, i32 0) preallocated(%foo) 2600 ; initialize %b 2601 call void @bar(i32 42, ptr preallocated(%foo) %a) ["preallocated"(token %t)] 2602 2603.. _ob_gc_live: 2604 2605GC Live Operand Bundles 2606^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2607 2608A "gc-live" operand bundle is only valid on a :ref:`gc.statepoint <gc_statepoint>` 2609intrinsic. The operand bundle must contain every pointer to a garbage collected 2610object which potentially needs to be updated by the garbage collector. 2611 2612When lowered, any relocated value will be recorded in the corresponding 2613:ref:`stackmap entry <statepoint-stackmap-format>`. See the intrinsic description 2614for further details. 2615 2616ObjC ARC Attached Call Operand Bundles 2617^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2618 2619A ``"clang.arc.attachedcall"`` operand bundle on a call indicates the call is 2620implicitly followed by a marker instruction and a call to an ObjC runtime 2621function that uses the result of the call. The operand bundle takes a mandatory 2622pointer to the runtime function (``@objc_retainAutoreleasedReturnValue`` or 2623``@objc_unsafeClaimAutoreleasedReturnValue``). 2624The return value of a call with this bundle is used by a call to 2625``@llvm.objc.clang.arc.noop.use`` unless the called function's return type is 2626void, in which case the operand bundle is ignored. 2627 2628.. code-block:: llvm 2629 2630 ; The marker instruction and a runtime function call are inserted after the call 2631 ; to @foo. 2632 call ptr @foo() [ "clang.arc.attachedcall"(ptr @objc_retainAutoreleasedReturnValue) ] 2633 call ptr @foo() [ "clang.arc.attachedcall"(ptr @objc_unsafeClaimAutoreleasedReturnValue) ] 2634 2635The operand bundle is needed to ensure the call is immediately followed by the 2636marker instruction and the ObjC runtime call in the final output. 2637 2638.. _ob_ptrauth: 2639 2640Pointer Authentication Operand Bundles 2641^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2642 2643Pointer Authentication operand bundles are characterized by the 2644``"ptrauth"`` operand bundle tag. They are described in the 2645`Pointer Authentication <PointerAuth.html#operand-bundle>`__ document. 2646 2647.. _moduleasm: 2648 2649Module-Level Inline Assembly 2650---------------------------- 2651 2652Modules may contain "module-level inline asm" blocks, which corresponds 2653to the GCC "file scope inline asm" blocks. These blocks are internally 2654concatenated by LLVM and treated as a single unit, but may be separated 2655in the ``.ll`` file if desired. The syntax is very simple: 2656 2657.. code-block:: llvm 2658 2659 module asm "inline asm code goes here" 2660 module asm "more can go here" 2661 2662The strings can contain any character by escaping non-printable 2663characters. The escape sequence used is simply "\\xx" where "xx" is the 2664two digit hex code for the number. 2665 2666Note that the assembly string *must* be parseable by LLVM's integrated assembler 2667(unless it is disabled), even when emitting a ``.s`` file. 2668 2669.. _langref_datalayout: 2670 2671Data Layout 2672----------- 2673 2674A module may specify a target specific data layout string that specifies 2675how data is to be laid out in memory. The syntax for the data layout is 2676simply: 2677 2678.. code-block:: llvm 2679 2680 target datalayout = "layout specification" 2681 2682The *layout specification* consists of a list of specifications 2683separated by the minus sign character ('-'). Each specification starts 2684with a letter and may include other information after the letter to 2685define some aspect of the data layout. The specifications accepted are 2686as follows: 2687 2688``E`` 2689 Specifies that the target lays out data in big-endian form. That is, 2690 the bits with the most significance have the lowest address 2691 location. 2692``e`` 2693 Specifies that the target lays out data in little-endian form. That 2694 is, the bits with the least significance have the lowest address 2695 location. 2696``S<size>`` 2697 Specifies the natural alignment of the stack in bits. Alignment 2698 promotion of stack variables is limited to the natural stack 2699 alignment to avoid dynamic stack realignment. The stack alignment 2700 must be a multiple of 8-bits. If omitted, the natural stack 2701 alignment defaults to "unspecified", which does not prevent any 2702 alignment promotions. 2703``P<address space>`` 2704 Specifies the address space that corresponds to program memory. 2705 Harvard architectures can use this to specify what space LLVM 2706 should place things such as functions into. If omitted, the 2707 program memory space defaults to the default address space of 0, 2708 which corresponds to a Von Neumann architecture that has code 2709 and data in the same space. 2710``G<address space>`` 2711 Specifies the address space to be used by default when creating global 2712 variables. If omitted, the globals address space defaults to the default 2713 address space 0. 2714 Note: variable declarations without an address space are always created in 2715 address space 0, this property only affects the default value to be used 2716 when creating globals without additional contextual information (e.g. in 2717 LLVM passes). 2718``A<address space>`` 2719 Specifies the address space of objects created by '``alloca``'. 2720 Defaults to the default address space of 0. 2721``p[n]:<size>:<abi>[:<pref>][:<idx>]`` 2722 This specifies the *size* of a pointer and its ``<abi>`` and 2723 ``<pref>``\erred alignments for address space ``n``. ``<pref>`` is optional 2724 and defaults to ``<abi>``. The fourth parameter ``<idx>`` is the size of the 2725 index that used for address calculation. If not 2726 specified, the default index size is equal to the pointer size. All sizes 2727 are in bits. The address space, ``n``, is optional, and if not specified, 2728 denotes the default address space 0. The value of ``n`` must be 2729 in the range [1,2^23). 2730``i<size>:<abi>[:<pref>]`` 2731 This specifies the alignment for an integer type of a given bit 2732 ``<size>``. The value of ``<size>`` must be in the range [1,2^23). 2733 ``<pref>`` is optional and defaults to ``<abi>``. 2734``v<size>:<abi>[:<pref>]`` 2735 This specifies the alignment for a vector type of a given bit 2736 ``<size>``. The value of ``<size>`` must be in the range [1,2^23). 2737 ``<pref>`` is optional and defaults to ``<abi>``. 2738``f<size>:<abi>[:<pref>]`` 2739 This specifies the alignment for a floating-point type of a given bit 2740 ``<size>``. Only values of ``<size>`` that are supported by the target 2741 will work. 32 (float) and 64 (double) are supported on all targets; 80 2742 or 128 (different flavors of long double) are also supported on some 2743 targets. The value of ``<size>`` must be in the range [1,2^23). 2744 ``<pref>`` is optional and defaults to ``<abi>``. 2745``a:<abi>[:<pref>]`` 2746 This specifies the alignment for an object of aggregate type. 2747 ``<pref>`` is optional and defaults to ``<abi>``. 2748``F<type><abi>`` 2749 This specifies the alignment for function pointers. 2750 The options for ``<type>`` are: 2751 2752 * ``i``: The alignment of function pointers is independent of the alignment 2753 of functions, and is a multiple of ``<abi>``. 2754 * ``n``: The alignment of function pointers is a multiple of the explicit 2755 alignment specified on the function, and is a multiple of ``<abi>``. 2756``m:<mangling>`` 2757 If present, specifies that llvm names are mangled in the output. Symbols 2758 prefixed with the mangling escape character ``\01`` are passed through 2759 directly to the assembler without the escape character. The mangling style 2760 options are 2761 2762 * ``e``: ELF mangling: Private symbols get a ``.L`` prefix. 2763 * ``l``: GOFF mangling: Private symbols get a ``@`` prefix. 2764 * ``m``: Mips mangling: Private symbols get a ``$`` prefix. 2765 * ``o``: Mach-O mangling: Private symbols get ``L`` prefix. Other 2766 symbols get a ``_`` prefix. 2767 * ``x``: Windows x86 COFF mangling: Private symbols get the usual prefix. 2768 Regular C symbols get a ``_`` prefix. Functions with ``__stdcall``, 2769 ``__fastcall``, and ``__vectorcall`` have custom mangling that appends 2770 ``@N`` where N is the number of bytes used to pass parameters. C++ symbols 2771 starting with ``?`` are not mangled in any way. 2772 * ``w``: Windows COFF mangling: Similar to ``x``, except that normal C 2773 symbols do not receive a ``_`` prefix. 2774 * ``a``: XCOFF mangling: Private symbols get a ``L..`` prefix. 2775``n<size1>:<size2>:<size3>...`` 2776 This specifies a set of native integer widths for the target CPU in 2777 bits. For example, it might contain ``n32`` for 32-bit PowerPC, 2778 ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of 2779 this set are considered to support most general arithmetic operations 2780 efficiently. 2781``ni:<address space0>:<address space1>:<address space2>...`` 2782 This specifies pointer types with the specified address spaces 2783 as :ref:`Non-Integral Pointer Type <nointptrtype>` s. The ``0`` 2784 address space cannot be specified as non-integral. 2785 2786On every specification that takes a ``<abi>:<pref>``, specifying the 2787``<pref>`` alignment is optional. If omitted, the preceding ``:`` 2788should be omitted too and ``<pref>`` will be equal to ``<abi>``. 2789 2790When constructing the data layout for a given target, LLVM starts with a 2791default set of specifications which are then (possibly) overridden by 2792the specifications in the ``datalayout`` keyword. The default 2793specifications are given in this list: 2794 2795- ``e`` - little endian 2796- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment. 2797- ``p[n]:64:64:64`` - Other address spaces are assumed to be the 2798 same as the default address space. 2799- ``S0`` - natural stack alignment is unspecified 2800- ``i1:8:8`` - i1 is 8-bit (byte) aligned 2801- ``i8:8:8`` - i8 is 8-bit (byte) aligned 2802- ``i16:16:16`` - i16 is 16-bit aligned 2803- ``i32:32:32`` - i32 is 32-bit aligned 2804- ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred 2805 alignment of 64-bits 2806- ``f16:16:16`` - half is 16-bit aligned 2807- ``f32:32:32`` - float is 32-bit aligned 2808- ``f64:64:64`` - double is 64-bit aligned 2809- ``f128:128:128`` - quad is 128-bit aligned 2810- ``v64:64:64`` - 64-bit vector is 64-bit aligned 2811- ``v128:128:128`` - 128-bit vector is 128-bit aligned 2812- ``a:0:64`` - aggregates are 64-bit aligned 2813 2814When LLVM is determining the alignment for a given type, it uses the 2815following rules: 2816 2817#. If the type sought is an exact match for one of the specifications, 2818 that specification is used. 2819#. If no match is found, and the type sought is an integer type, then 2820 the smallest integer type that is larger than the bitwidth of the 2821 sought type is used. If none of the specifications are larger than 2822 the bitwidth then the largest integer type is used. For example, 2823 given the default specifications above, the i7 type will use the 2824 alignment of i8 (next largest) while both i65 and i256 will use the 2825 alignment of i64 (largest specified). 2826 2827The function of the data layout string may not be what you expect. 2828Notably, this is not a specification from the frontend of what alignment 2829the code generator should use. 2830 2831Instead, if specified, the target data layout is required to match what 2832the ultimate *code generator* expects. This string is used by the 2833mid-level optimizers to improve code, and this only works if it matches 2834what the ultimate code generator uses. There is no way to generate IR 2835that does not embed this target-specific detail into the IR. If you 2836don't specify the string, the default specifications will be used to 2837generate a Data Layout and the optimization phases will operate 2838accordingly and introduce target specificity into the IR with respect to 2839these default specifications. 2840 2841.. _langref_triple: 2842 2843Target Triple 2844------------- 2845 2846A module may specify a target triple string that describes the target 2847host. The syntax for the target triple is simply: 2848 2849.. code-block:: llvm 2850 2851 target triple = "x86_64-apple-macosx10.7.0" 2852 2853The *target triple* string consists of a series of identifiers delimited 2854by the minus sign character ('-'). The canonical forms are: 2855 2856:: 2857 2858 ARCHITECTURE-VENDOR-OPERATING_SYSTEM 2859 ARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT 2860 2861This information is passed along to the backend so that it generates 2862code for the proper architecture. It's possible to override this on the 2863command line with the ``-mtriple`` command line option. 2864 2865.. _objectlifetime: 2866 2867Object Lifetime 2868---------------------- 2869 2870A memory object, or simply object, is a region of a memory space that is 2871reserved by a memory allocation such as :ref:`alloca <i_alloca>`, heap 2872allocation calls, and global variable definitions. 2873Once it is allocated, the bytes stored in the region can only be read or written 2874through a pointer that is :ref:`based on <pointeraliasing>` the allocation 2875value. 2876If a pointer that is not based on the object tries to read or write to the 2877object, it is undefined behavior. 2878 2879A lifetime of a memory object is a property that decides its accessibility. 2880Unless stated otherwise, a memory object is alive since its allocation, and 2881dead after its deallocation. 2882It is undefined behavior to access a memory object that isn't alive, but 2883operations that don't dereference it such as 2884:ref:`getelementptr <i_getelementptr>`, :ref:`ptrtoint <i_ptrtoint>` and 2885:ref:`icmp <i_icmp>` return a valid result. 2886This explains code motion of these instructions across operations that 2887impact the object's lifetime. 2888A stack object's lifetime can be explicitly specified using 2889:ref:`llvm.lifetime.start <int_lifestart>` and 2890:ref:`llvm.lifetime.end <int_lifeend>` intrinsic function calls. 2891 2892.. _pointeraliasing: 2893 2894Pointer Aliasing Rules 2895---------------------- 2896 2897Any memory access must be done through a pointer value associated with 2898an address range of the memory access, otherwise the behavior is 2899undefined. Pointer values are associated with address ranges according 2900to the following rules: 2901 2902- A pointer value is associated with the addresses associated with any 2903 value it is *based* on. 2904- An address of a global variable is associated with the address range 2905 of the variable's storage. 2906- The result value of an allocation instruction is associated with the 2907 address range of the allocated storage. 2908- A null pointer in the default address-space is associated with no 2909 address. 2910- An :ref:`undef value <undefvalues>` in *any* address-space is 2911 associated with no address. 2912- An integer constant other than zero or a pointer value returned from 2913 a function not defined within LLVM may be associated with address 2914 ranges allocated through mechanisms other than those provided by 2915 LLVM. Such ranges shall not overlap with any ranges of addresses 2916 allocated by mechanisms provided by LLVM. 2917 2918A pointer value is *based* on another pointer value according to the 2919following rules: 2920 2921- A pointer value formed from a scalar ``getelementptr`` operation is *based* on 2922 the pointer-typed operand of the ``getelementptr``. 2923- The pointer in lane *l* of the result of a vector ``getelementptr`` operation 2924 is *based* on the pointer in lane *l* of the vector-of-pointers-typed operand 2925 of the ``getelementptr``. 2926- The result value of a ``bitcast`` is *based* on the operand of the 2927 ``bitcast``. 2928- A pointer value formed by an ``inttoptr`` is *based* on all pointer 2929 values that contribute (directly or indirectly) to the computation of 2930 the pointer's value. 2931- The "*based* on" relationship is transitive. 2932 2933Note that this definition of *"based"* is intentionally similar to the 2934definition of *"based"* in C99, though it is slightly weaker. 2935 2936LLVM IR does not associate types with memory. The result type of a 2937``load`` merely indicates the size and alignment of the memory from 2938which to load, as well as the interpretation of the value. The first 2939operand type of a ``store`` similarly only indicates the size and 2940alignment of the store. 2941 2942Consequently, type-based alias analysis, aka TBAA, aka 2943``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR. 2944:ref:`Metadata <metadata>` may be used to encode additional information 2945which specialized optimization passes may use to implement type-based 2946alias analysis. 2947 2948.. _pointercapture: 2949 2950Pointer Capture 2951--------------- 2952 2953Given a function call and a pointer that is passed as an argument or stored in 2954the memory before the call, a pointer is *captured* by the call if it makes a 2955copy of any part of the pointer that outlives the call. 2956To be precise, a pointer is captured if one or more of the following conditions 2957hold: 2958 29591. The call stores any bit of the pointer carrying information into a place, 2960 and the stored bits can be read from the place by the caller after this call 2961 exits. 2962 2963.. code-block:: llvm 2964 2965 @glb = global ptr null 2966 @glb2 = global ptr null 2967 @glb3 = global ptr null 2968 @glbi = global i32 0 2969 2970 define ptr @f(ptr %a, ptr %b, ptr %c, ptr %d, ptr %e) { 2971 store ptr %a, ptr @glb ; %a is captured by this call 2972 2973 store ptr %b, ptr @glb2 ; %b isn't captured because the stored value is overwritten by the store below 2974 store ptr null, ptr @glb2 2975 2976 store ptr %c, ptr @glb3 2977 call void @g() ; If @g makes a copy of %c that outlives this call (@f), %c is captured 2978 store ptr null, ptr @glb3 2979 2980 %i = ptrtoint ptr %d to i64 2981 %j = trunc i64 %i to i32 2982 store i32 %j, ptr @glbi ; %d is captured 2983 2984 ret ptr %e ; %e is captured 2985 } 2986 29872. The call stores any bit of the pointer carrying information into a place, 2988 and the stored bits can be safely read from the place by another thread via 2989 synchronization. 2990 2991.. code-block:: llvm 2992 2993 @lock = global i1 true 2994 2995 define void @f(ptr %a) { 2996 store ptr %a, ptr* @glb 2997 store atomic i1 false, ptr @lock release ; %a is captured because another thread can safely read @glb 2998 store ptr null, ptr @glb 2999 ret void 3000 } 3001 30023. The call's behavior depends on any bit of the pointer carrying information. 3003 3004.. code-block:: llvm 3005 3006 @glb = global i8 0 3007 3008 define void @f(ptr %a) { 3009 %c = icmp eq ptr %a, @glb 3010 br i1 %c, label %BB_EXIT, label %BB_CONTINUE ; escapes %a 3011 BB_EXIT: 3012 call void @exit() 3013 unreachable 3014 BB_CONTINUE: 3015 ret void 3016 } 3017 30184. The pointer is used in a volatile access as its address. 3019 3020 3021.. _volatile: 3022 3023Volatile Memory Accesses 3024------------------------ 3025 3026Certain memory accesses, such as :ref:`load <i_load>`'s, 3027:ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be 3028marked ``volatile``. The optimizers must not change the number of 3029volatile operations or change their order of execution relative to other 3030volatile operations. The optimizers *may* change the order of volatile 3031operations relative to non-volatile operations. This is not Java's 3032"volatile" and has no cross-thread synchronization behavior. 3033 3034A volatile load or store may have additional target-specific semantics. 3035Any volatile operation can have side effects, and any volatile operation 3036can read and/or modify state which is not accessible via a regular load 3037or store in this module. Volatile operations may use addresses which do 3038not point to memory (like MMIO registers). This means the compiler may 3039not use a volatile operation to prove a non-volatile access to that 3040address has defined behavior. 3041 3042The allowed side-effects for volatile accesses are limited. If a 3043non-volatile store to a given address would be legal, a volatile 3044operation may modify the memory at that address. A volatile operation 3045may not modify any other memory accessible by the module being compiled. 3046A volatile operation may not call any code in the current module. 3047 3048The compiler may assume execution will continue after a volatile operation, 3049so operations which modify memory or may have undefined behavior can be 3050hoisted past a volatile operation. 3051 3052As an exception to the preceding rule, the compiler may not assume execution 3053will continue after a volatile store operation. This restriction is necessary 3054to support the somewhat common pattern in C of intentionally storing to an 3055invalid pointer to crash the program. In the future, it might make sense to 3056allow frontends to control this behavior. 3057 3058IR-level volatile loads and stores cannot safely be optimized into llvm.memcpy 3059or llvm.memmove intrinsics even when those intrinsics are flagged volatile. 3060Likewise, the backend should never split or merge target-legal volatile 3061load/store instructions. Similarly, IR-level volatile loads and stores cannot 3062change from integer to floating-point or vice versa. 3063 3064.. admonition:: Rationale 3065 3066 Platforms may rely on volatile loads and stores of natively supported 3067 data width to be executed as single instruction. For example, in C 3068 this holds for an l-value of volatile primitive type with native 3069 hardware support, but not necessarily for aggregate types. The 3070 frontend upholds these expectations, which are intentionally 3071 unspecified in the IR. The rules above ensure that IR transformations 3072 do not violate the frontend's contract with the language. 3073 3074.. _memmodel: 3075 3076Memory Model for Concurrent Operations 3077-------------------------------------- 3078 3079The LLVM IR does not define any way to start parallel threads of 3080execution or to register signal handlers. Nonetheless, there are 3081platform-specific ways to create them, and we define LLVM IR's behavior 3082in their presence. This model is inspired by the C++0x memory model. 3083 3084For a more informal introduction to this model, see the :doc:`Atomics`. 3085 3086We define a *happens-before* partial order as the least partial order 3087that 3088 3089- Is a superset of single-thread program order, and 3090- When a *synchronizes-with* ``b``, includes an edge from ``a`` to 3091 ``b``. *Synchronizes-with* pairs are introduced by platform-specific 3092 techniques, like pthread locks, thread creation, thread joining, 3093 etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering 3094 Constraints <ordering>`). 3095 3096Note that program order does not introduce *happens-before* edges 3097between a thread and signals executing inside that thread. 3098 3099Every (defined) read operation (load instructions, memcpy, atomic 3100loads/read-modify-writes, etc.) R reads a series of bytes written by 3101(defined) write operations (store instructions, atomic 3102stores/read-modify-writes, memcpy, etc.). For the purposes of this 3103section, initialized globals are considered to have a write of the 3104initializer which is atomic and happens before any other read or write 3105of the memory in question. For each byte of a read R, R\ :sub:`byte` 3106may see any write to the same byte, except: 3107 3108- If write\ :sub:`1` happens before write\ :sub:`2`, and 3109 write\ :sub:`2` happens before R\ :sub:`byte`, then 3110 R\ :sub:`byte` does not see write\ :sub:`1`. 3111- If R\ :sub:`byte` happens before write\ :sub:`3`, then 3112 R\ :sub:`byte` does not see write\ :sub:`3`. 3113 3114Given that definition, R\ :sub:`byte` is defined as follows: 3115 3116- If R is volatile, the result is target-dependent. (Volatile is 3117 supposed to give guarantees which can support ``sig_atomic_t`` in 3118 C/C++, and may be used for accesses to addresses that do not behave 3119 like normal memory. It does not generally provide cross-thread 3120 synchronization.) 3121- Otherwise, if there is no write to the same byte that happens before 3122 R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte. 3123- Otherwise, if R\ :sub:`byte` may see exactly one write, 3124 R\ :sub:`byte` returns the value written by that write. 3125- Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may 3126 see are atomic, it chooses one of the values written. See the :ref:`Atomic 3127 Memory Ordering Constraints <ordering>` section for additional 3128 constraints on how the choice is made. 3129- Otherwise R\ :sub:`byte` returns ``undef``. 3130 3131R returns the value composed of the series of bytes it read. This 3132implies that some bytes within the value may be ``undef`` **without** 3133the entire value being ``undef``. Note that this only defines the 3134semantics of the operation; it doesn't mean that targets will emit more 3135than one instruction to read the series of bytes. 3136 3137Note that in cases where none of the atomic intrinsics are used, this 3138model places only one restriction on IR transformations on top of what 3139is required for single-threaded execution: introducing a store to a byte 3140which might not otherwise be stored is not allowed in general. 3141(Specifically, in the case where another thread might write to and read 3142from an address, introducing a store can change a load that may see 3143exactly one write into a load that may see multiple writes.) 3144 3145.. _ordering: 3146 3147Atomic Memory Ordering Constraints 3148---------------------------------- 3149 3150Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`, 3151:ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`, 3152:ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take 3153ordering parameters that determine which other atomic instructions on 3154the same address they *synchronize with*. These semantics are borrowed 3155from Java and C++0x, but are somewhat more colloquial. If these 3156descriptions aren't precise enough, check those specs (see spec 3157references in the :doc:`atomics guide <Atomics>`). 3158:ref:`fence <i_fence>` instructions treat these orderings somewhat 3159differently since they don't take an address. See that instruction's 3160documentation for details. 3161 3162For a simpler introduction to the ordering constraints, see the 3163:doc:`Atomics`. 3164 3165``unordered`` 3166 The set of values that can be read is governed by the happens-before 3167 partial order. A value cannot be read unless some operation wrote 3168 it. This is intended to provide a guarantee strong enough to model 3169 Java's non-volatile shared variables. This ordering cannot be 3170 specified for read-modify-write operations; it is not strong enough 3171 to make them atomic in any interesting way. 3172``monotonic`` 3173 In addition to the guarantees of ``unordered``, there is a single 3174 total order for modifications by ``monotonic`` operations on each 3175 address. All modification orders must be compatible with the 3176 happens-before order. There is no guarantee that the modification 3177 orders can be combined to a global total order for the whole program 3178 (and this often will not be possible). The read in an atomic 3179 read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and 3180 :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification 3181 order immediately before the value it writes. If one atomic read 3182 happens before another atomic read of the same address, the later 3183 read must see the same value or a later value in the address's 3184 modification order. This disallows reordering of ``monotonic`` (or 3185 stronger) operations on the same address. If an address is written 3186 ``monotonic``-ally by one thread, and other threads ``monotonic``-ally 3187 read that address repeatedly, the other threads must eventually see 3188 the write. This corresponds to the C++0x/C1x 3189 ``memory_order_relaxed``. 3190``acquire`` 3191 In addition to the guarantees of ``monotonic``, a 3192 *synchronizes-with* edge may be formed with a ``release`` operation. 3193 This is intended to model C++'s ``memory_order_acquire``. 3194``release`` 3195 In addition to the guarantees of ``monotonic``, if this operation 3196 writes a value which is subsequently read by an ``acquire`` 3197 operation, it *synchronizes-with* that operation. (This isn't a 3198 complete description; see the C++0x definition of a release 3199 sequence.) This corresponds to the C++0x/C1x 3200 ``memory_order_release``. 3201``acq_rel`` (acquire+release) 3202 Acts as both an ``acquire`` and ``release`` operation on its 3203 address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``. 3204``seq_cst`` (sequentially consistent) 3205 In addition to the guarantees of ``acq_rel`` (``acquire`` for an 3206 operation that only reads, ``release`` for an operation that only 3207 writes), there is a global total order on all 3208 sequentially-consistent operations on all addresses, which is 3209 consistent with the *happens-before* partial order and with the 3210 modification orders of all the affected addresses. Each 3211 sequentially-consistent read sees the last preceding write to the 3212 same address in this global order. This corresponds to the C++0x/C1x 3213 ``memory_order_seq_cst`` and Java volatile. 3214 3215.. _syncscope: 3216 3217If an atomic operation is marked ``syncscope("singlethread")``, it only 3218*synchronizes with* and only participates in the seq\_cst total orderings of 3219other operations running in the same thread (for example, in signal handlers). 3220 3221If an atomic operation is marked ``syncscope("<target-scope>")``, where 3222``<target-scope>`` is a target specific synchronization scope, then it is target 3223dependent if it *synchronizes with* and participates in the seq\_cst total 3224orderings of other operations. 3225 3226Otherwise, an atomic operation that is not marked ``syncscope("singlethread")`` 3227or ``syncscope("<target-scope>")`` *synchronizes with* and participates in the 3228seq\_cst total orderings of other operations that are not marked 3229``syncscope("singlethread")`` or ``syncscope("<target-scope>")``. 3230 3231.. _floatenv: 3232 3233Floating-Point Environment 3234-------------------------- 3235 3236The default LLVM floating-point environment assumes that floating-point 3237instructions do not have side effects. Results assume the round-to-nearest 3238rounding mode. No floating-point exception state is maintained in this 3239environment. Therefore, there is no attempt to create or preserve invalid 3240operation (SNaN) or division-by-zero exceptions. 3241 3242The benefit of this exception-free assumption is that floating-point 3243operations may be speculated freely without any other fast-math relaxations 3244to the floating-point model. 3245 3246Code that requires different behavior than this should use the 3247:ref:`Constrained Floating-Point Intrinsics <constrainedfp>`. 3248 3249.. _fastmath: 3250 3251Fast-Math Flags 3252--------------- 3253 3254LLVM IR floating-point operations (:ref:`fneg <i_fneg>`, :ref:`fadd <i_fadd>`, 3255:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`, 3256:ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`), :ref:`phi <i_phi>`, 3257:ref:`select <i_select>` and :ref:`call <i_call>` 3258may use the following flags to enable otherwise unsafe 3259floating-point transformations. 3260 3261``nnan`` 3262 No NaNs - Allow optimizations to assume the arguments and result are not 3263 NaN. If an argument is a nan, or the result would be a nan, it produces 3264 a :ref:`poison value <poisonvalues>` instead. 3265 3266``ninf`` 3267 No Infs - Allow optimizations to assume the arguments and result are not 3268 +/-Inf. If an argument is +/-Inf, or the result would be +/-Inf, it 3269 produces a :ref:`poison value <poisonvalues>` instead. 3270 3271``nsz`` 3272 No Signed Zeros - Allow optimizations to treat the sign of a zero 3273 argument or result as insignificant. This does not imply that -0.0 3274 is poison and/or guaranteed to not exist in the operation. 3275 3276``arcp`` 3277 Allow Reciprocal - Allow optimizations to use the reciprocal of an 3278 argument rather than perform division. 3279 3280``contract`` 3281 Allow floating-point contraction (e.g. fusing a multiply followed by an 3282 addition into a fused multiply-and-add). This does not enable reassociating 3283 to form arbitrary contractions. For example, ``(a*b) + (c*d) + e`` can not 3284 be transformed into ``(a*b) + ((c*d) + e)`` to create two fma operations. 3285 3286``afn`` 3287 Approximate functions - Allow substitution of approximate calculations for 3288 functions (sin, log, sqrt, etc). See floating-point intrinsic definitions 3289 for places where this can apply to LLVM's intrinsic math functions. 3290 3291``reassoc`` 3292 Allow reassociation transformations for floating-point instructions. 3293 This may dramatically change results in floating-point. 3294 3295``fast`` 3296 This flag implies all of the others. 3297 3298.. _uselistorder: 3299 3300Use-list Order Directives 3301------------------------- 3302 3303Use-list directives encode the in-memory order of each use-list, allowing the 3304order to be recreated. ``<order-indexes>`` is a comma-separated list of 3305indexes that are assigned to the referenced value's uses. The referenced 3306value's use-list is immediately sorted by these indexes. 3307 3308Use-list directives may appear at function scope or global scope. They are not 3309instructions, and have no effect on the semantics of the IR. When they're at 3310function scope, they must appear after the terminator of the final basic block. 3311 3312If basic blocks have their address taken via ``blockaddress()`` expressions, 3313``uselistorder_bb`` can be used to reorder their use-lists from outside their 3314function's scope. 3315 3316:Syntax: 3317 3318:: 3319 3320 uselistorder <ty> <value>, { <order-indexes> } 3321 uselistorder_bb @function, %block { <order-indexes> } 3322 3323:Examples: 3324 3325:: 3326 3327 define void @foo(i32 %arg1, i32 %arg2) { 3328 entry: 3329 ; ... instructions ... 3330 bb: 3331 ; ... instructions ... 3332 3333 ; At function scope. 3334 uselistorder i32 %arg1, { 1, 0, 2 } 3335 uselistorder label %bb, { 1, 0 } 3336 } 3337 3338 ; At global scope. 3339 uselistorder ptr @global, { 1, 2, 0 } 3340 uselistorder i32 7, { 1, 0 } 3341 uselistorder i32 (i32) @bar, { 1, 0 } 3342 uselistorder_bb @foo, %bb, { 5, 1, 3, 2, 0, 4 } 3343 3344.. _source_filename: 3345 3346Source Filename 3347--------------- 3348 3349The *source filename* string is set to the original module identifier, 3350which will be the name of the compiled source file when compiling from 3351source through the clang front end, for example. It is then preserved through 3352the IR and bitcode. 3353 3354This is currently necessary to generate a consistent unique global 3355identifier for local functions used in profile data, which prepends the 3356source file name to the local function name. 3357 3358The syntax for the source file name is simply: 3359 3360.. code-block:: text 3361 3362 source_filename = "/path/to/source.c" 3363 3364.. _typesystem: 3365 3366Type System 3367=========== 3368 3369The LLVM type system is one of the most important features of the 3370intermediate representation. Being typed enables a number of 3371optimizations to be performed on the intermediate representation 3372directly, without having to do extra analyses on the side before the 3373transformation. A strong type system makes it easier to read the 3374generated code and enables novel analyses and transformations that are 3375not feasible to perform on normal three address code representations. 3376 3377.. _t_void: 3378 3379Void Type 3380--------- 3381 3382:Overview: 3383 3384 3385The void type does not represent any value and has no size. 3386 3387:Syntax: 3388 3389 3390:: 3391 3392 void 3393 3394 3395.. _t_function: 3396 3397Function Type 3398------------- 3399 3400:Overview: 3401 3402 3403The function type can be thought of as a function signature. It consists of a 3404return type and a list of formal parameter types. The return type of a function 3405type is a void type or first class type --- except for :ref:`label <t_label>` 3406and :ref:`metadata <t_metadata>` types. 3407 3408:Syntax: 3409 3410:: 3411 3412 <returntype> (<parameter list>) 3413 3414...where '``<parameter list>``' is a comma-separated list of type 3415specifiers. Optionally, the parameter list may include a type ``...``, which 3416indicates that the function takes a variable number of arguments. Variable 3417argument functions can access their arguments with the :ref:`variable argument 3418handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type 3419except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`. 3420 3421:Examples: 3422 3423+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3424| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` | 3425+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3426| ``i32 (ptr, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` argument and returns an integer. This is the signature for ``printf`` in LLVM. | 3427+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3428| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values | 3429+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3430 3431.. _t_firstclass: 3432 3433First Class Types 3434----------------- 3435 3436The :ref:`first class <t_firstclass>` types are perhaps the most important. 3437Values of these types are the only ones which can be produced by 3438instructions. 3439 3440.. _t_single_value: 3441 3442Single Value Types 3443^^^^^^^^^^^^^^^^^^ 3444 3445These are the types that are valid in registers from CodeGen's perspective. 3446 3447.. _t_integer: 3448 3449Integer Type 3450"""""""""""" 3451 3452:Overview: 3453 3454The integer type is a very simple type that simply specifies an 3455arbitrary bit width for the integer type desired. Any bit width from 1 3456bit to 2\ :sup:`23`\ (about 8 million) can be specified. 3457 3458:Syntax: 3459 3460:: 3461 3462 iN 3463 3464The number of bits the integer will occupy is specified by the ``N`` 3465value. 3466 3467Examples: 3468********* 3469 3470+----------------+------------------------------------------------+ 3471| ``i1`` | a single-bit integer. | 3472+----------------+------------------------------------------------+ 3473| ``i32`` | a 32-bit integer. | 3474+----------------+------------------------------------------------+ 3475| ``i1942652`` | a really big integer of over 1 million bits. | 3476+----------------+------------------------------------------------+ 3477 3478.. _t_floating: 3479 3480Floating-Point Types 3481"""""""""""""""""""" 3482 3483.. list-table:: 3484 :header-rows: 1 3485 3486 * - Type 3487 - Description 3488 3489 * - ``half`` 3490 - 16-bit floating-point value 3491 3492 * - ``bfloat`` 3493 - 16-bit "brain" floating-point value (7-bit significand). Provides the 3494 same number of exponent bits as ``float``, so that it matches its dynamic 3495 range, but with greatly reduced precision. Used in Intel's AVX-512 BF16 3496 extensions and Arm's ARMv8.6-A extensions, among others. 3497 3498 * - ``float`` 3499 - 32-bit floating-point value 3500 3501 * - ``double`` 3502 - 64-bit floating-point value 3503 3504 * - ``fp128`` 3505 - 128-bit floating-point value (113-bit significand) 3506 3507 * - ``x86_fp80`` 3508 - 80-bit floating-point value (X87) 3509 3510 * - ``ppc_fp128`` 3511 - 128-bit floating-point value (two 64-bits) 3512 3513The binary format of half, float, double, and fp128 correspond to the 3514IEEE-754-2008 specifications for binary16, binary32, binary64, and binary128 3515respectively. 3516 3517X86_amx Type 3518"""""""""""" 3519 3520:Overview: 3521 3522The x86_amx type represents a value held in an AMX tile register on an x86 3523machine. The operations allowed on it are quite limited. Only few intrinsics 3524are allowed: stride load and store, zero and dot product. No instruction is 3525allowed for this type. There are no arguments, arrays, pointers, vectors 3526or constants of this type. 3527 3528:Syntax: 3529 3530:: 3531 3532 x86_amx 3533 3534 3535X86_mmx Type 3536"""""""""""" 3537 3538:Overview: 3539 3540The x86_mmx type represents a value held in an MMX register on an x86 3541machine. The operations allowed on it are quite limited: parameters and 3542return values, load and store, and bitcast. User-specified MMX 3543instructions are represented as intrinsic or asm calls with arguments 3544and/or results of this type. There are no arrays, vectors or constants 3545of this type. 3546 3547:Syntax: 3548 3549:: 3550 3551 x86_mmx 3552 3553 3554.. _t_pointer: 3555 3556Pointer Type 3557"""""""""""" 3558 3559:Overview: 3560 3561The pointer type ``ptr`` is used to specify memory locations. Pointers are 3562commonly used to reference objects in memory. 3563 3564Pointer types may have an optional address space attribute defining the 3565numbered address space where the pointed-to object resides. The default 3566address space is number zero. The semantics of non-zero address spaces 3567are target-specific. For example, ``ptr addrspace(5)`` is a pointer 3568to address space 5. 3569 3570Prior to LLVM 15, pointer types also specified a pointee type, such as 3571``i8*``, ``[4 x i32]*`` or ``i32 (i32*)*``. In LLVM 15, such "typed 3572pointers" are still supported under non-default options. See the 3573`opaque pointers document <OpaquePointers.html>`__ for more information. 3574 3575.. _t_vector: 3576 3577Vector Type 3578""""""""""" 3579 3580:Overview: 3581 3582A vector type is a simple derived type that represents a vector of 3583elements. Vector types are used when multiple primitive data are 3584operated in parallel using a single instruction (SIMD). A vector type 3585requires a size (number of elements), an underlying primitive data type, 3586and a scalable property to represent vectors where the exact hardware 3587vector length is unknown at compile time. Vector types are considered 3588:ref:`first class <t_firstclass>`. 3589 3590:Memory Layout: 3591 3592In general vector elements are laid out in memory in the same way as 3593:ref:`array types <t_array>`. Such an analogy works fine as long as the vector 3594elements are byte sized. However, when the elements of the vector aren't byte 3595sized it gets a bit more complicated. One way to describe the layout is by 3596describing what happens when a vector such as <N x iM> is bitcasted to an 3597integer type with N*M bits, and then following the rules for storing such an 3598integer to memory. 3599 3600A bitcast from a vector type to a scalar integer type will see the elements 3601being packed together (without padding). The order in which elements are 3602inserted in the integer depends on endianess. For little endian element zero 3603is put in the least significant bits of the integer, and for big endian 3604element zero is put in the most significant bits. 3605 3606Using a vector such as ``<i4 1, i4 2, i4 3, i4 5>`` as an example, together 3607with the analogy that we can replace a vector store by a bitcast followed by 3608an integer store, we get this for big endian: 3609 3610.. code-block:: llvm 3611 3612 %val = bitcast <4 x i4> <i4 1, i4 2, i4 3, i4 5> to i16 3613 3614 ; Bitcasting from a vector to an integral type can be seen as 3615 ; concatenating the values: 3616 ; %val now has the hexadecimal value 0x1235. 3617 3618 store i16 %val, ptr %ptr 3619 3620 ; In memory the content will be (8-bit addressing): 3621 ; 3622 ; [%ptr + 0]: 00010010 (0x12) 3623 ; [%ptr + 1]: 00110101 (0x35) 3624 3625The same example for little endian: 3626 3627.. code-block:: llvm 3628 3629 %val = bitcast <4 x i4> <i4 1, i4 2, i4 3, i4 5> to i16 3630 3631 ; Bitcasting from a vector to an integral type can be seen as 3632 ; concatenating the values: 3633 ; %val now has the hexadecimal value 0x5321. 3634 3635 store i16 %val, ptr %ptr 3636 3637 ; In memory the content will be (8-bit addressing): 3638 ; 3639 ; [%ptr + 0]: 01010011 (0x53) 3640 ; [%ptr + 1]: 00100001 (0x21) 3641 3642When ``<N*M>`` isn't evenly divisible by the byte size the exact memory layout 3643is unspecified (just like it is for an integral type of the same size). This 3644is because different targets could put the padding at different positions when 3645the type size is smaller than the type's store size. 3646 3647:Syntax: 3648 3649:: 3650 3651 < <# elements> x <elementtype> > ; Fixed-length vector 3652 < vscale x <# elements> x <elementtype> > ; Scalable vector 3653 3654The number of elements is a constant integer value larger than 0; 3655elementtype may be any integer, floating-point or pointer type. Vectors 3656of size zero are not allowed. For scalable vectors, the total number of 3657elements is a constant multiple (called vscale) of the specified number 3658of elements; vscale is a positive integer that is unknown at compile time 3659and the same hardware-dependent constant for all scalable vectors at run 3660time. The size of a specific scalable vector type is thus constant within 3661IR, even if the exact size in bytes cannot be determined until run time. 3662 3663:Examples: 3664 3665+------------------------+----------------------------------------------------+ 3666| ``<4 x i32>`` | Vector of 4 32-bit integer values. | 3667+------------------------+----------------------------------------------------+ 3668| ``<8 x float>`` | Vector of 8 32-bit floating-point values. | 3669+------------------------+----------------------------------------------------+ 3670| ``<2 x i64>`` | Vector of 2 64-bit integer values. | 3671+------------------------+----------------------------------------------------+ 3672| ``<4 x ptr>`` | Vector of 4 pointers | 3673+------------------------+----------------------------------------------------+ 3674| ``<vscale x 4 x i32>`` | Vector with a multiple of 4 32-bit integer values. | 3675+------------------------+----------------------------------------------------+ 3676 3677.. _t_label: 3678 3679Label Type 3680^^^^^^^^^^ 3681 3682:Overview: 3683 3684The label type represents code labels. 3685 3686:Syntax: 3687 3688:: 3689 3690 label 3691 3692.. _t_token: 3693 3694Token Type 3695^^^^^^^^^^ 3696 3697:Overview: 3698 3699The token type is used when a value is associated with an instruction 3700but all uses of the value must not attempt to introspect or obscure it. 3701As such, it is not appropriate to have a :ref:`phi <i_phi>` or 3702:ref:`select <i_select>` of type token. 3703 3704:Syntax: 3705 3706:: 3707 3708 token 3709 3710 3711 3712.. _t_metadata: 3713 3714Metadata Type 3715^^^^^^^^^^^^^ 3716 3717:Overview: 3718 3719The metadata type represents embedded metadata. No derived types may be 3720created from metadata except for :ref:`function <t_function>` arguments. 3721 3722:Syntax: 3723 3724:: 3725 3726 metadata 3727 3728.. _t_aggregate: 3729 3730Aggregate Types 3731^^^^^^^^^^^^^^^ 3732 3733Aggregate Types are a subset of derived types that can contain multiple 3734member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are 3735aggregate types. :ref:`Vectors <t_vector>` are not considered to be 3736aggregate types. 3737 3738.. _t_array: 3739 3740Array Type 3741"""""""""" 3742 3743:Overview: 3744 3745The array type is a very simple derived type that arranges elements 3746sequentially in memory. The array type requires a size (number of 3747elements) and an underlying data type. 3748 3749:Syntax: 3750 3751:: 3752 3753 [<# elements> x <elementtype>] 3754 3755The number of elements is a constant integer value; ``elementtype`` may 3756be any type with a size. 3757 3758:Examples: 3759 3760+------------------+--------------------------------------+ 3761| ``[40 x i32]`` | Array of 40 32-bit integer values. | 3762+------------------+--------------------------------------+ 3763| ``[41 x i32]`` | Array of 41 32-bit integer values. | 3764+------------------+--------------------------------------+ 3765| ``[4 x i8]`` | Array of 4 8-bit integer values. | 3766+------------------+--------------------------------------+ 3767 3768Here are some examples of multidimensional arrays: 3769 3770+-----------------------------+----------------------------------------------------------+ 3771| ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. | 3772+-----------------------------+----------------------------------------------------------+ 3773| ``[12 x [10 x float]]`` | 12x10 array of single precision floating-point values. | 3774+-----------------------------+----------------------------------------------------------+ 3775| ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. | 3776+-----------------------------+----------------------------------------------------------+ 3777 3778There is no restriction on indexing beyond the end of the array implied 3779by a static type (though there are restrictions on indexing beyond the 3780bounds of an allocated object in some cases). This means that 3781single-dimension 'variable sized array' addressing can be implemented in 3782LLVM with a zero length array type. An implementation of 'pascal style 3783arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for 3784example. 3785 3786.. _t_struct: 3787 3788Structure Type 3789"""""""""""""" 3790 3791:Overview: 3792 3793The structure type is used to represent a collection of data members 3794together in memory. The elements of a structure may be any type that has 3795a size. 3796 3797Structures in memory are accessed using '``load``' and '``store``' by 3798getting a pointer to a field with the '``getelementptr``' instruction. 3799Structures in registers are accessed using the '``extractvalue``' and 3800'``insertvalue``' instructions. 3801 3802Structures may optionally be "packed" structures, which indicate that 3803the alignment of the struct is one byte, and that there is no padding 3804between the elements. In non-packed structs, padding between field types 3805is inserted as defined by the DataLayout string in the module, which is 3806required to match what the underlying code generator expects. 3807 3808Structures can either be "literal" or "identified". A literal structure 3809is defined inline with other types (e.g. ``[2 x {i32, i32}]``) whereas 3810identified types are always defined at the top level with a name. 3811Literal types are uniqued by their contents and can never be recursive 3812or opaque since there is no way to write one. Identified types can be 3813recursive, can be opaqued, and are never uniqued. 3814 3815:Syntax: 3816 3817:: 3818 3819 %T1 = type { <type list> } ; Identified normal struct type 3820 %T2 = type <{ <type list> }> ; Identified packed struct type 3821 3822:Examples: 3823 3824+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3825| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values | 3826+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3827| ``{ float, ptr }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>`. | 3828+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3829| ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. | 3830+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 3831 3832.. _t_opaque: 3833 3834Opaque Structure Types 3835"""""""""""""""""""""" 3836 3837:Overview: 3838 3839Opaque structure types are used to represent structure types that 3840do not have a body specified. This corresponds (for example) to the C 3841notion of a forward declared structure. They can be named (``%X``) or 3842unnamed (``%52``). 3843 3844:Syntax: 3845 3846:: 3847 3848 %X = type opaque 3849 %52 = type opaque 3850 3851:Examples: 3852 3853+--------------+-------------------+ 3854| ``opaque`` | An opaque type. | 3855+--------------+-------------------+ 3856 3857.. _constants: 3858 3859Constants 3860========= 3861 3862LLVM has several different basic types of constants. This section 3863describes them all and their syntax. 3864 3865Simple Constants 3866---------------- 3867 3868**Boolean constants** 3869 The two strings '``true``' and '``false``' are both valid constants 3870 of the ``i1`` type. 3871**Integer constants** 3872 Standard integers (such as '4') are constants of the 3873 :ref:`integer <t_integer>` type. Negative numbers may be used with 3874 integer types. 3875**Floating-point constants** 3876 Floating-point constants use standard decimal notation (e.g. 3877 123.421), exponential notation (e.g. 1.23421e+2), or a more precise 3878 hexadecimal notation (see below). The assembler requires the exact 3879 decimal value of a floating-point constant. For example, the 3880 assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating 3881 decimal in binary. Floating-point constants must have a 3882 :ref:`floating-point <t_floating>` type. 3883**Null pointer constants** 3884 The identifier '``null``' is recognized as a null pointer constant 3885 and must be of :ref:`pointer type <t_pointer>`. 3886**Token constants** 3887 The identifier '``none``' is recognized as an empty token constant 3888 and must be of :ref:`token type <t_token>`. 3889 3890The one non-intuitive notation for constants is the hexadecimal form of 3891floating-point constants. For example, the form 3892'``double 0x432ff973cafa8000``' is equivalent to (but harder to read 3893than) '``double 4.5e+15``'. The only time hexadecimal floating-point 3894constants are required (and the only time that they are generated by the 3895disassembler) is when a floating-point constant must be emitted but it 3896cannot be represented as a decimal floating-point number in a reasonable 3897number of digits. For example, NaN's, infinities, and other special 3898values are represented in their IEEE hexadecimal format so that assembly 3899and disassembly do not cause any bits to change in the constants. 3900 3901When using the hexadecimal form, constants of types bfloat, half, float, and 3902double are represented using the 16-digit form shown above (which matches the 3903IEEE754 representation for double); bfloat, half and float values must, however, 3904be exactly representable as bfloat, IEEE 754 half, and IEEE 754 single 3905precision respectively. Hexadecimal format is always used for long double, and 3906there are three forms of long double. The 80-bit format used by x86 is 3907represented as ``0xK`` followed by 20 hexadecimal digits. The 128-bit format 3908used by PowerPC (two adjacent doubles) is represented by ``0xM`` followed by 32 3909hexadecimal digits. The IEEE 128-bit format is represented by ``0xL`` followed 3910by 32 hexadecimal digits. Long doubles will only work if they match the long 3911double format on your target. The IEEE 16-bit format (half precision) is 3912represented by ``0xH`` followed by 4 hexadecimal digits. The bfloat 16-bit 3913format is represented by ``0xR`` followed by 4 hexadecimal digits. All 3914hexadecimal formats are big-endian (sign bit at the left). 3915 3916There are no constants of type x86_mmx and x86_amx. 3917 3918.. _complexconstants: 3919 3920Complex Constants 3921----------------- 3922 3923Complex constants are a (potentially recursive) combination of simple 3924constants and smaller complex constants. 3925 3926**Structure constants** 3927 Structure constants are represented with notation similar to 3928 structure type definitions (a comma separated list of elements, 3929 surrounded by braces (``{}``)). For example: 3930 "``{ i32 4, float 17.0, ptr @G }``", where "``@G``" is declared as 3931 "``@G = external global i32``". Structure constants must have 3932 :ref:`structure type <t_struct>`, and the number and types of elements 3933 must match those specified by the type. 3934**Array constants** 3935 Array constants are represented with notation similar to array type 3936 definitions (a comma separated list of elements, surrounded by 3937 square brackets (``[]``)). For example: 3938 "``[ i32 42, i32 11, i32 74 ]``". Array constants must have 3939 :ref:`array type <t_array>`, and the number and types of elements must 3940 match those specified by the type. As a special case, character array 3941 constants may also be represented as a double-quoted string using the ``c`` 3942 prefix. For example: "``c"Hello World\0A\00"``". 3943**Vector constants** 3944 Vector constants are represented with notation similar to vector 3945 type definitions (a comma separated list of elements, surrounded by 3946 less-than/greater-than's (``<>``)). For example: 3947 "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants 3948 must have :ref:`vector type <t_vector>`, and the number and types of 3949 elements must match those specified by the type. 3950**Zero initialization** 3951 The string '``zeroinitializer``' can be used to zero initialize a 3952 value to zero of *any* type, including scalar and 3953 :ref:`aggregate <t_aggregate>` types. This is often used to avoid 3954 having to print large zero initializers (e.g. for large arrays) and 3955 is always exactly equivalent to using explicit zero initializers. 3956**Metadata node** 3957 A metadata node is a constant tuple without types. For example: 3958 "``!{!0, !{!2, !0}, !"test"}``". Metadata can reference constant values, 3959 for example: "``!{!0, i32 0, ptr @global, ptr @function, !"str"}``". 3960 Unlike other typed constants that are meant to be interpreted as part of 3961 the instruction stream, metadata is a place to attach additional 3962 information such as debug info. 3963 3964Global Variable and Function Addresses 3965-------------------------------------- 3966 3967The addresses of :ref:`global variables <globalvars>` and 3968:ref:`functions <functionstructure>` are always implicitly valid 3969(link-time) constants. These constants are explicitly referenced when 3970the :ref:`identifier for the global <identifiers>` is used and always have 3971:ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM 3972file: 3973 3974.. code-block:: llvm 3975 3976 @X = global i32 17 3977 @Y = global i32 42 3978 @Z = global [2 x ptr] [ ptr @X, ptr @Y ] 3979 3980.. _undefvalues: 3981 3982Undefined Values 3983---------------- 3984 3985The string '``undef``' can be used anywhere a constant is expected, and 3986indicates that the user of the value may receive an unspecified 3987bit-pattern. Undefined values may be of any type (other than '``label``' 3988or '``void``') and be used anywhere a constant is permitted. 3989 3990.. note:: 3991 3992 A '``poison``' value (decribed in the next section) should be used instead of 3993 '``undef``' whenever possible. Poison values are stronger than undef, and 3994 enable more optimizations. Just the existence of '``undef``' blocks certain 3995 optimizations (see the examples below). 3996 3997Undefined values are useful because they indicate to the compiler that 3998the program is well defined no matter what value is used. This gives the 3999compiler more freedom to optimize. Here are some examples of 4000(potentially surprising) transformations that are valid (in pseudo IR): 4001 4002.. code-block:: llvm 4003 4004 %A = add %X, undef 4005 %B = sub %X, undef 4006 %C = xor %X, undef 4007 Safe: 4008 %A = undef 4009 %B = undef 4010 %C = undef 4011 4012This is safe because all of the output bits are affected by the undef 4013bits. Any output bit can have a zero or one depending on the input bits. 4014 4015.. code-block:: llvm 4016 4017 %A = or %X, undef 4018 %B = and %X, undef 4019 Safe: 4020 %A = -1 4021 %B = 0 4022 Safe: 4023 %A = %X ;; By choosing undef as 0 4024 %B = %X ;; By choosing undef as -1 4025 Unsafe: 4026 %A = undef 4027 %B = undef 4028 4029These logical operations have bits that are not always affected by the 4030input. For example, if ``%X`` has a zero bit, then the output of the 4031'``and``' operation will always be a zero for that bit, no matter what 4032the corresponding bit from the '``undef``' is. As such, it is unsafe to 4033optimize or assume that the result of the '``and``' is '``undef``'. 4034However, it is safe to assume that all bits of the '``undef``' could be 40350, and optimize the '``and``' to 0. Likewise, it is safe to assume that 4036all the bits of the '``undef``' operand to the '``or``' could be set, 4037allowing the '``or``' to be folded to -1. 4038 4039.. code-block:: llvm 4040 4041 %A = select undef, %X, %Y 4042 %B = select undef, 42, %Y 4043 %C = select %X, %Y, undef 4044 Safe: 4045 %A = %X (or %Y) 4046 %B = 42 (or %Y) 4047 %C = %Y (if %Y is provably not poison; unsafe otherwise) 4048 Unsafe: 4049 %A = undef 4050 %B = undef 4051 %C = undef 4052 4053This set of examples shows that undefined '``select``' (and conditional 4054branch) conditions can go *either way*, but they have to come from one 4055of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were 4056both known to have a clear low bit, then ``%A`` would have to have a 4057cleared low bit. However, in the ``%C`` example, the optimizer is 4058allowed to assume that the '``undef``' operand could be the same as 4059``%Y`` if ``%Y`` is provably not '``poison``', allowing the whole '``select``' 4060to be eliminated. This is because '``poison``' is stronger than '``undef``'. 4061 4062.. code-block:: llvm 4063 4064 %A = xor undef, undef 4065 4066 %B = undef 4067 %C = xor %B, %B 4068 4069 %D = undef 4070 %E = icmp slt %D, 4 4071 %F = icmp gte %D, 4 4072 4073 Safe: 4074 %A = undef 4075 %B = undef 4076 %C = undef 4077 %D = undef 4078 %E = undef 4079 %F = undef 4080 4081This example points out that two '``undef``' operands are not 4082necessarily the same. This can be surprising to people (and also matches 4083C semantics) where they assume that "``X^X``" is always zero, even if 4084``X`` is undefined. This isn't true for a number of reasons, but the 4085short answer is that an '``undef``' "variable" can arbitrarily change 4086its value over its "live range". This is true because the variable 4087doesn't actually *have a live range*. Instead, the value is logically 4088read from arbitrary registers that happen to be around when needed, so 4089the value is not necessarily consistent over time. In fact, ``%A`` and 4090``%C`` need to have the same semantics or the core LLVM "replace all 4091uses with" concept would not hold. 4092 4093To ensure all uses of a given register observe the same value (even if 4094'``undef``'), the :ref:`freeze instruction <i_freeze>` can be used. 4095 4096.. code-block:: llvm 4097 4098 %A = sdiv undef, %X 4099 %B = sdiv %X, undef 4100 Safe: 4101 %A = 0 4102 b: unreachable 4103 4104These examples show the crucial difference between an *undefined value* 4105and *undefined behavior*. An undefined value (like '``undef``') is 4106allowed to have an arbitrary bit-pattern. This means that the ``%A`` 4107operation can be constant folded to '``0``', because the '``undef``' 4108could be zero, and zero divided by any value is zero. 4109However, in the second example, we can make a more aggressive 4110assumption: because the ``undef`` is allowed to be an arbitrary value, 4111we are allowed to assume that it could be zero. Since a divide by zero 4112has *undefined behavior*, we are allowed to assume that the operation 4113does not execute at all. This allows us to delete the divide and all 4114code after it. Because the undefined operation "can't happen", the 4115optimizer can assume that it occurs in dead code. 4116 4117.. code-block:: text 4118 4119 a: store undef -> %X 4120 b: store %X -> undef 4121 Safe: 4122 a: <deleted> (if the stored value in %X is provably not poison) 4123 b: unreachable 4124 4125A store *of* an undefined value can be assumed to not have any effect; 4126we can assume that the value is overwritten with bits that happen to 4127match what was already there. This argument is only valid if the stored value 4128is provably not ``poison``. However, a store *to* an undefined 4129location could clobber arbitrary memory, therefore, it has undefined 4130behavior. 4131 4132Branching on an undefined value is undefined behavior. 4133This explains optimizations that depend on branch conditions to construct 4134predicates, such as Correlated Value Propagation and Global Value Numbering. 4135In case of switch instruction, the branch condition should be frozen, otherwise 4136it is undefined behavior. 4137 4138.. code-block:: llvm 4139 4140 Unsafe: 4141 br undef, BB1, BB2 ; UB 4142 4143 %X = and i32 undef, 255 4144 switch %X, label %ret [ .. ] ; UB 4145 4146 store undef, ptr %ptr 4147 %X = load ptr %ptr ; %X is undef 4148 switch i8 %X, label %ret [ .. ] ; UB 4149 4150 Safe: 4151 %X = or i8 undef, 255 ; always 255 4152 switch i8 %X, label %ret [ .. ] ; Well-defined 4153 4154 %X = freeze i1 undef 4155 br %X, BB1, BB2 ; Well-defined (non-deterministic jump) 4156 4157 4158 4159.. _poisonvalues: 4160 4161Poison Values 4162------------- 4163 4164A poison value is a result of an erroneous operation. 4165In order to facilitate speculative execution, many instructions do not 4166invoke immediate undefined behavior when provided with illegal operands, 4167and return a poison value instead. 4168The string '``poison``' can be used anywhere a constant is expected, and 4169operations such as :ref:`add <i_add>` with the ``nsw`` flag can produce 4170a poison value. 4171 4172Most instructions return '``poison``' when one of their arguments is 4173'``poison``'. A notable exception is the :ref:`select instruction <i_select>`. 4174Propagation of poison can be stopped with the 4175:ref:`freeze instruction <i_freeze>`. 4176 4177It is correct to replace a poison value with an 4178:ref:`undef value <undefvalues>` or any value of the type. 4179 4180This means that immediate undefined behavior occurs if a poison value is 4181used as an instruction operand that has any values that trigger undefined 4182behavior. Notably this includes (but is not limited to): 4183 4184- The pointer operand of a :ref:`load <i_load>`, :ref:`store <i_store>` or 4185 any other pointer dereferencing instruction (independent of address 4186 space). 4187- The divisor operand of a ``udiv``, ``sdiv``, ``urem`` or ``srem`` 4188 instruction. 4189- The condition operand of a :ref:`br <i_br>` instruction. 4190- The callee operand of a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 4191 instruction. 4192- The parameter operand of a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 4193 instruction, when the function or invoking call site has a ``noundef`` 4194 attribute in the corresponding position. 4195- The operand of a :ref:`ret <i_ret>` instruction if the function or invoking 4196 call site has a `noundef` attribute in the return value position. 4197 4198Here are some examples: 4199 4200.. code-block:: llvm 4201 4202 entry: 4203 %poison = sub nuw i32 0, 1 ; Results in a poison value. 4204 %poison2 = sub i32 poison, 1 ; Also results in a poison value. 4205 %still_poison = and i32 %poison, 0 ; 0, but also poison. 4206 %poison_yet_again = getelementptr i32, ptr @h, i32 %still_poison 4207 store i32 0, ptr %poison_yet_again ; Undefined behavior due to 4208 ; store to poison. 4209 4210 store i32 %poison, ptr @g ; Poison value stored to memory. 4211 %poison3 = load i32, ptr @g ; Poison value loaded back from memory. 4212 4213 %poison4 = load i16, ptr @g ; Returns a poison value. 4214 %poison5 = load i64, ptr @g ; Returns a poison value. 4215 4216 %cmp = icmp slt i32 %poison, 0 ; Returns a poison value. 4217 br i1 %cmp, label %end, label %end ; undefined behavior 4218 4219 end: 4220 4221.. _welldefinedvalues: 4222 4223Well-Defined Values 4224------------------- 4225 4226Given a program execution, a value is *well defined* if the value does not 4227have an undef bit and is not poison in the execution. 4228An aggregate value or vector is well defined if its elements are well defined. 4229The padding of an aggregate isn't considered, since it isn't visible 4230without storing it into memory and loading it with a different type. 4231 4232A constant of a :ref:`single value <t_single_value>`, non-vector type is well 4233defined if it is neither '``undef``' constant nor '``poison``' constant. 4234The result of :ref:`freeze instruction <i_freeze>` is well defined regardless 4235of its operand. 4236 4237.. _blockaddress: 4238 4239Addresses of Basic Blocks 4240------------------------- 4241 4242``blockaddress(@function, %block)`` 4243 4244The '``blockaddress``' constant computes the address of the specified 4245basic block in the specified function. 4246 4247It always has an ``ptr addrspace(P)`` type, where ``P`` is the address space 4248of the function containing ``%block`` (usually ``addrspace(0)``). 4249 4250Taking the address of the entry block is illegal. 4251 4252This value only has defined behavior when used as an operand to the 4253':ref:`indirectbr <i_indirectbr>`' or ':ref:`callbr <i_callbr>`'instruction, or 4254for comparisons against null. Pointer equality tests between labels addresses 4255results in undefined behavior --- though, again, comparison against null is ok, 4256and no label is equal to the null pointer. This may be passed around as an 4257opaque pointer sized value as long as the bits are not inspected. This 4258allows ``ptrtoint`` and arithmetic to be performed on these values so 4259long as the original value is reconstituted before the ``indirectbr`` or 4260``callbr`` instruction. 4261 4262Finally, some targets may provide defined semantics when using the value 4263as the operand to an inline assembly, but that is target specific. 4264 4265.. _dso_local_equivalent: 4266 4267DSO Local Equivalent 4268-------------------- 4269 4270``dso_local_equivalent @func`` 4271 4272A '``dso_local_equivalent``' constant represents a function which is 4273functionally equivalent to a given function, but is always defined in the 4274current linkage unit. The resulting pointer has the same type as the underlying 4275function. The resulting pointer is permitted, but not required, to be different 4276from a pointer to the function, and it may have different values in different 4277translation units. 4278 4279The target function may not have ``extern_weak`` linkage. 4280 4281``dso_local_equivalent`` can be implemented as such: 4282 4283- If the function has local linkage, hidden visibility, or is 4284 ``dso_local``, ``dso_local_equivalent`` can be implemented as simply a pointer 4285 to the function. 4286- ``dso_local_equivalent`` can be implemented with a stub that tail-calls the 4287 function. Many targets support relocations that resolve at link time to either 4288 a function or a stub for it, depending on if the function is defined within the 4289 linkage unit; LLVM will use this when available. (This is commonly called a 4290 "PLT stub".) On other targets, the stub may need to be emitted explicitly. 4291 4292This can be used wherever a ``dso_local`` instance of a function is needed without 4293needing to explicitly make the original function ``dso_local``. An instance where 4294this can be used is for static offset calculations between a function and some other 4295``dso_local`` symbol. This is especially useful for the Relative VTables C++ ABI, 4296where dynamic relocations for function pointers in VTables can be replaced with 4297static relocations for offsets between the VTable and virtual functions which 4298may not be ``dso_local``. 4299 4300This is currently only supported for ELF binary formats. 4301 4302.. _no_cfi: 4303 4304No CFI 4305------ 4306 4307``no_cfi @func`` 4308 4309With `Control-Flow Integrity (CFI) 4310<https://clang.llvm.org/docs/ControlFlowIntegrity.html>`_, a '``no_cfi``' 4311constant represents a function reference that does not get replaced with a 4312reference to the CFI jump table in the ``LowerTypeTests`` pass. These constants 4313may be useful in low-level programs, such as operating system kernels, which 4314need to refer to the actual function body. 4315 4316.. _constantexprs: 4317 4318Constant Expressions 4319-------------------- 4320 4321Constant expressions are used to allow expressions involving other 4322constants to be used as constants. Constant expressions may be of any 4323:ref:`first class <t_firstclass>` type and may involve any LLVM operation 4324that does not have side effects (e.g. load and call are not supported). 4325The following is the syntax for constant expressions: 4326 4327``trunc (CST to TYPE)`` 4328 Perform the :ref:`trunc operation <i_trunc>` on constants. 4329``zext (CST to TYPE)`` 4330 Perform the :ref:`zext operation <i_zext>` on constants. 4331``sext (CST to TYPE)`` 4332 Perform the :ref:`sext operation <i_sext>` on constants. 4333``fptrunc (CST to TYPE)`` 4334 Truncate a floating-point constant to another floating-point type. 4335 The size of CST must be larger than the size of TYPE. Both types 4336 must be floating-point. 4337``fpext (CST to TYPE)`` 4338 Floating-point extend a constant to another type. The size of CST 4339 must be smaller or equal to the size of TYPE. Both types must be 4340 floating-point. 4341``fptoui (CST to TYPE)`` 4342 Convert a floating-point constant to the corresponding unsigned 4343 integer constant. TYPE must be a scalar or vector integer type. CST 4344 must be of scalar or vector floating-point type. Both CST and TYPE 4345 must be scalars, or vectors of the same number of elements. If the 4346 value won't fit in the integer type, the result is a 4347 :ref:`poison value <poisonvalues>`. 4348``fptosi (CST to TYPE)`` 4349 Convert a floating-point constant to the corresponding signed 4350 integer constant. TYPE must be a scalar or vector integer type. CST 4351 must be of scalar or vector floating-point type. Both CST and TYPE 4352 must be scalars, or vectors of the same number of elements. If the 4353 value won't fit in the integer type, the result is a 4354 :ref:`poison value <poisonvalues>`. 4355``uitofp (CST to TYPE)`` 4356 Convert an unsigned integer constant to the corresponding 4357 floating-point constant. TYPE must be a scalar or vector floating-point 4358 type. CST must be of scalar or vector integer type. Both CST and TYPE must 4359 be scalars, or vectors of the same number of elements. 4360``sitofp (CST to TYPE)`` 4361 Convert a signed integer constant to the corresponding floating-point 4362 constant. TYPE must be a scalar or vector floating-point type. 4363 CST must be of scalar or vector integer type. Both CST and TYPE must 4364 be scalars, or vectors of the same number of elements. 4365``ptrtoint (CST to TYPE)`` 4366 Perform the :ref:`ptrtoint operation <i_ptrtoint>` on constants. 4367``inttoptr (CST to TYPE)`` 4368 Perform the :ref:`inttoptr operation <i_inttoptr>` on constants. 4369 This one is *really* dangerous! 4370``bitcast (CST to TYPE)`` 4371 Convert a constant, CST, to another TYPE. 4372 The constraints of the operands are the same as those for the 4373 :ref:`bitcast instruction <i_bitcast>`. 4374``addrspacecast (CST to TYPE)`` 4375 Convert a constant pointer or constant vector of pointer, CST, to another 4376 TYPE in a different address space. The constraints of the operands are the 4377 same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`. 4378``getelementptr (TY, CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (TY, CSTPTR, IDX0, IDX1, ...)`` 4379 Perform the :ref:`getelementptr operation <i_getelementptr>` on 4380 constants. As with the :ref:`getelementptr <i_getelementptr>` 4381 instruction, the index list may have one or more indexes, which are 4382 required to make sense for the type of "pointer to TY". 4383``select (COND, VAL1, VAL2)`` 4384 Perform the :ref:`select operation <i_select>` on constants. 4385``icmp COND (VAL1, VAL2)`` 4386 Perform the :ref:`icmp operation <i_icmp>` on constants. 4387``fcmp COND (VAL1, VAL2)`` 4388 Perform the :ref:`fcmp operation <i_fcmp>` on constants. 4389``extractelement (VAL, IDX)`` 4390 Perform the :ref:`extractelement operation <i_extractelement>` on 4391 constants. 4392``insertelement (VAL, ELT, IDX)`` 4393 Perform the :ref:`insertelement operation <i_insertelement>` on 4394 constants. 4395``shufflevector (VEC1, VEC2, IDXMASK)`` 4396 Perform the :ref:`shufflevector operation <i_shufflevector>` on 4397 constants. 4398``extractvalue (VAL, IDX0, IDX1, ...)`` 4399 Perform the :ref:`extractvalue operation <i_extractvalue>` on 4400 constants. The index list is interpreted in a similar manner as 4401 indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At 4402 least one index value must be specified. 4403``insertvalue (VAL, ELT, IDX0, IDX1, ...)`` 4404 Perform the :ref:`insertvalue operation <i_insertvalue>` on constants. 4405 The index list is interpreted in a similar manner as indices in a 4406 ':ref:`getelementptr <i_getelementptr>`' operation. At least one index 4407 value must be specified. 4408``OPCODE (LHS, RHS)`` 4409 Perform the specified operation of the LHS and RHS constants. OPCODE 4410 may be any of the :ref:`binary <binaryops>` or :ref:`bitwise 4411 binary <bitwiseops>` operations. The constraints on operands are 4412 the same as those for the corresponding instruction (e.g. no bitwise 4413 operations on floating-point values are allowed). 4414 4415Other Values 4416============ 4417 4418.. _inlineasmexprs: 4419 4420Inline Assembler Expressions 4421---------------------------- 4422 4423LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level 4424Inline Assembly <moduleasm>`) through the use of a special value. This value 4425represents the inline assembler as a template string (containing the 4426instructions to emit), a list of operand constraints (stored as a string), a 4427flag that indicates whether or not the inline asm expression has side effects, 4428and a flag indicating whether the function containing the asm needs to align its 4429stack conservatively. 4430 4431The template string supports argument substitution of the operands using "``$``" 4432followed by a number, to indicate substitution of the given register/memory 4433location, as specified by the constraint string. "``${NUM:MODIFIER}``" may also 4434be used, where ``MODIFIER`` is a target-specific annotation for how to print the 4435operand (See :ref:`inline-asm-modifiers`). 4436 4437A literal "``$``" may be included by using "``$$``" in the template. To include 4438other special characters into the output, the usual "``\XX``" escapes may be 4439used, just as in other strings. Note that after template substitution, the 4440resulting assembly string is parsed by LLVM's integrated assembler unless it is 4441disabled -- even when emitting a ``.s`` file -- and thus must contain assembly 4442syntax known to LLVM. 4443 4444LLVM also supports a few more substitutions useful for writing inline assembly: 4445 4446- ``${:uid}``: Expands to a decimal integer unique to this inline assembly blob. 4447 This substitution is useful when declaring a local label. Many standard 4448 compiler optimizations, such as inlining, may duplicate an inline asm blob. 4449 Adding a blob-unique identifier ensures that the two labels will not conflict 4450 during assembly. This is used to implement `GCC's %= special format 4451 string <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_. 4452- ``${:comment}``: Expands to the comment character of the current target's 4453 assembly dialect. This is usually ``#``, but many targets use other strings, 4454 such as ``;``, ``//``, or ``!``. 4455- ``${:private}``: Expands to the assembler private label prefix. Labels with 4456 this prefix will not appear in the symbol table of the assembled object. 4457 Typically the prefix is ``L``, but targets may use other strings. ``.L`` is 4458 relatively popular. 4459 4460LLVM's support for inline asm is modeled closely on the requirements of Clang's 4461GCC-compatible inline-asm support. Thus, the feature-set and the constraint and 4462modifier codes listed here are similar or identical to those in GCC's inline asm 4463support. However, to be clear, the syntax of the template and constraint strings 4464described here is *not* the same as the syntax accepted by GCC and Clang, and, 4465while most constraint letters are passed through as-is by Clang, some get 4466translated to other codes when converting from the C source to the LLVM 4467assembly. 4468 4469An example inline assembler expression is: 4470 4471.. code-block:: llvm 4472 4473 i32 (i32) asm "bswap $0", "=r,r" 4474 4475Inline assembler expressions may **only** be used as the callee operand 4476of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction. 4477Thus, typically we have: 4478 4479.. code-block:: llvm 4480 4481 %X = call i32 asm "bswap $0", "=r,r"(i32 %Y) 4482 4483Inline asms with side effects not visible in the constraint list must be 4484marked as having side effects. This is done through the use of the 4485'``sideeffect``' keyword, like so: 4486 4487.. code-block:: llvm 4488 4489 call void asm sideeffect "eieio", ""() 4490 4491In some cases inline asms will contain code that will not work unless 4492the stack is aligned in some way, such as calls or SSE instructions on 4493x86, yet will not contain code that does that alignment within the asm. 4494The compiler should make conservative assumptions about what the asm 4495might contain and should generate its usual stack alignment code in the 4496prologue if the '``alignstack``' keyword is present: 4497 4498.. code-block:: llvm 4499 4500 call void asm alignstack "eieio", ""() 4501 4502Inline asms also support using non-standard assembly dialects. The 4503assumed dialect is ATT. When the '``inteldialect``' keyword is present, 4504the inline asm is using the Intel dialect. Currently, ATT and Intel are 4505the only supported dialects. An example is: 4506 4507.. code-block:: llvm 4508 4509 call void asm inteldialect "eieio", ""() 4510 4511In the case that the inline asm might unwind the stack, 4512the '``unwind``' keyword must be used, so that the compiler emits 4513unwinding information: 4514 4515.. code-block:: llvm 4516 4517 call void asm unwind "call func", ""() 4518 4519If the inline asm unwinds the stack and isn't marked with 4520the '``unwind``' keyword, the behavior is undefined. 4521 4522If multiple keywords appear, the '``sideeffect``' keyword must come 4523first, the '``alignstack``' keyword second, the '``inteldialect``' keyword 4524third and the '``unwind``' keyword last. 4525 4526Inline Asm Constraint String 4527^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4528 4529The constraint list is a comma-separated string, each element containing one or 4530more constraint codes. 4531 4532For each element in the constraint list an appropriate register or memory 4533operand will be chosen, and it will be made available to assembly template 4534string expansion as ``$0`` for the first constraint in the list, ``$1`` for the 4535second, etc. 4536 4537There are three different types of constraints, which are distinguished by a 4538prefix symbol in front of the constraint code: Output, Input, and Clobber. The 4539constraints must always be given in that order: outputs first, then inputs, then 4540clobbers. They cannot be intermingled. 4541 4542There are also three different categories of constraint codes: 4543 4544- Register constraint. This is either a register class, or a fixed physical 4545 register. This kind of constraint will allocate a register, and if necessary, 4546 bitcast the argument or result to the appropriate type. 4547- Memory constraint. This kind of constraint is for use with an instruction 4548 taking a memory operand. Different constraints allow for different addressing 4549 modes used by the target. 4550- Immediate value constraint. This kind of constraint is for an integer or other 4551 immediate value which can be rendered directly into an instruction. The 4552 various target-specific constraints allow the selection of a value in the 4553 proper range for the instruction you wish to use it with. 4554 4555Output constraints 4556"""""""""""""""""" 4557 4558Output constraints are specified by an "``=``" prefix (e.g. "``=r``"). This 4559indicates that the assembly will write to this operand, and the operand will 4560then be made available as a return value of the ``asm`` expression. Output 4561constraints do not consume an argument from the call instruction. (Except, see 4562below about indirect outputs). 4563 4564Normally, it is expected that no output locations are written to by the assembly 4565expression until *all* of the inputs have been read. As such, LLVM may assign 4566the same register to an output and an input. If this is not safe (e.g. if the 4567assembly contains two instructions, where the first writes to one output, and 4568the second reads an input and writes to a second output), then the "``&``" 4569modifier must be used (e.g. "``=&r``") to specify that the output is an 4570"early-clobber" output. Marking an output as "early-clobber" ensures that LLVM 4571will not use the same register for any inputs (other than an input tied to this 4572output). 4573 4574Input constraints 4575""""""""""""""""" 4576 4577Input constraints do not have a prefix -- just the constraint codes. Each input 4578constraint will consume one argument from the call instruction. It is not 4579permitted for the asm to write to any input register or memory location (unless 4580that input is tied to an output). Note also that multiple inputs may all be 4581assigned to the same register, if LLVM can determine that they necessarily all 4582contain the same value. 4583 4584Instead of providing a Constraint Code, input constraints may also "tie" 4585themselves to an output constraint, by providing an integer as the constraint 4586string. Tied inputs still consume an argument from the call instruction, and 4587take up a position in the asm template numbering as is usual -- they will simply 4588be constrained to always use the same register as the output they've been tied 4589to. For example, a constraint string of "``=r,0``" says to assign a register for 4590output, and use that register as an input as well (it being the 0'th 4591constraint). 4592 4593It is permitted to tie an input to an "early-clobber" output. In that case, no 4594*other* input may share the same register as the input tied to the early-clobber 4595(even when the other input has the same value). 4596 4597You may only tie an input to an output which has a register constraint, not a 4598memory constraint. Only a single input may be tied to an output. 4599 4600There is also an "interesting" feature which deserves a bit of explanation: if a 4601register class constraint allocates a register which is too small for the value 4602type operand provided as input, the input value will be split into multiple 4603registers, and all of them passed to the inline asm. 4604 4605However, this feature is often not as useful as you might think. 4606 4607Firstly, the registers are *not* guaranteed to be consecutive. So, on those 4608architectures that have instructions which operate on multiple consecutive 4609instructions, this is not an appropriate way to support them. (e.g. the 32-bit 4610SparcV8 has a 64-bit load, which instruction takes a single 32-bit register. The 4611hardware then loads into both the named register, and the next register. This 4612feature of inline asm would not be useful to support that.) 4613 4614A few of the targets provide a template string modifier allowing explicit access 4615to the second register of a two-register operand (e.g. MIPS ``L``, ``M``, and 4616``D``). On such an architecture, you can actually access the second allocated 4617register (yet, still, not any subsequent ones). But, in that case, you're still 4618probably better off simply splitting the value into two separate operands, for 4619clarity. (e.g. see the description of the ``A`` constraint on X86, which, 4620despite existing only for use with this feature, is not really a good idea to 4621use) 4622 4623Indirect inputs and outputs 4624""""""""""""""""""""""""""" 4625 4626Indirect output or input constraints can be specified by the "``*``" modifier 4627(which goes after the "``=``" in case of an output). This indicates that the asm 4628will write to or read from the contents of an *address* provided as an input 4629argument. (Note that in this way, indirect outputs act more like an *input* than 4630an output: just like an input, they consume an argument of the call expression, 4631rather than producing a return value. An indirect output constraint is an 4632"output" only in that the asm is expected to write to the contents of the input 4633memory location, instead of just read from it). 4634 4635This is most typically used for memory constraint, e.g. "``=*m``", to pass the 4636address of a variable as a value. 4637 4638It is also possible to use an indirect *register* constraint, but only on output 4639(e.g. "``=*r``"). This will cause LLVM to allocate a register for an output 4640value normally, and then, separately emit a store to the address provided as 4641input, after the provided inline asm. (It's not clear what value this 4642functionality provides, compared to writing the store explicitly after the asm 4643statement, and it can only produce worse code, since it bypasses many 4644optimization passes. I would recommend not using it.) 4645 4646Call arguments for indirect constraints must have pointer type and must specify 4647the :ref:`elementtype <attr_elementtype>` attribute to indicate the pointer 4648element type. 4649 4650Clobber constraints 4651""""""""""""""""""" 4652 4653A clobber constraint is indicated by a "``~``" prefix. A clobber does not 4654consume an input operand, nor generate an output. Clobbers cannot use any of the 4655general constraint code letters -- they may use only explicit register 4656constraints, e.g. "``~{eax}``". The one exception is that a clobber string of 4657"``~{memory}``" indicates that the assembly writes to arbitrary undeclared 4658memory locations -- not only the memory pointed to by a declared indirect 4659output. 4660 4661Note that clobbering named registers that are also present in output 4662constraints is not legal. 4663 4664Label constraints 4665""""""""""""""""" 4666 4667A label constraint is indicated by a "``!``" prefix and typically used in the 4668form ``"!i"``. Instead of consuming call arguments, label constraints consume 4669indirect destination labels of ``callbr`` instructions. 4670 4671Label constraints can only be used in conjunction with ``callbr`` and the 4672number of label constraints must match the number of indirect destination 4673labels in the ``callbr`` instruction. 4674 4675 4676Constraint Codes 4677"""""""""""""""" 4678After a potential prefix comes constraint code, or codes. 4679 4680A Constraint Code is either a single letter (e.g. "``r``"), a "``^``" character 4681followed by two letters (e.g. "``^wc``"), or "``{``" register-name "``}``" 4682(e.g. "``{eax}``"). 4683 4684The one and two letter constraint codes are typically chosen to be the same as 4685GCC's constraint codes. 4686 4687A single constraint may include one or more than constraint code in it, leaving 4688it up to LLVM to choose which one to use. This is included mainly for 4689compatibility with the translation of GCC inline asm coming from clang. 4690 4691There are two ways to specify alternatives, and either or both may be used in an 4692inline asm constraint list: 4693 46941) Append the codes to each other, making a constraint code set. E.g. "``im``" 4695 or "``{eax}m``". This means "choose any of the options in the set". The 4696 choice of constraint is made independently for each constraint in the 4697 constraint list. 4698 46992) Use "``|``" between constraint code sets, creating alternatives. Every 4700 constraint in the constraint list must have the same number of alternative 4701 sets. With this syntax, the same alternative in *all* of the items in the 4702 constraint list will be chosen together. 4703 4704Putting those together, you might have a two operand constraint string like 4705``"rm|r,ri|rm"``. This indicates that if operand 0 is ``r`` or ``m``, then 4706operand 1 may be one of ``r`` or ``i``. If operand 0 is ``r``, then operand 1 4707may be one of ``r`` or ``m``. But, operand 0 and 1 cannot both be of type m. 4708 4709However, the use of either of the alternatives features is *NOT* recommended, as 4710LLVM is not able to make an intelligent choice about which one to use. (At the 4711point it currently needs to choose, not enough information is available to do so 4712in a smart way.) Thus, it simply tries to make a choice that's most likely to 4713compile, not one that will be optimal performance. (e.g., given "``rm``", it'll 4714always choose to use memory, not registers). And, if given multiple registers, 4715or multiple register classes, it will simply choose the first one. (In fact, it 4716doesn't currently even ensure explicitly specified physical registers are 4717unique, so specifying multiple physical registers as alternatives, like 4718``{r11}{r12},{r11}{r12}``, will assign r11 to both operands, not at all what was 4719intended.) 4720 4721Supported Constraint Code List 4722"""""""""""""""""""""""""""""" 4723 4724The constraint codes are, in general, expected to behave the same way they do in 4725GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C 4726inline asm code which was supported by GCC. A mismatch in behavior between LLVM 4727and GCC likely indicates a bug in LLVM. 4728 4729Some constraint codes are typically supported by all targets: 4730 4731- ``r``: A register in the target's general purpose register class. 4732- ``m``: A memory address operand. It is target-specific what addressing modes 4733 are supported, typical examples are register, or register + register offset, 4734 or register + immediate offset (of some target-specific size). 4735- ``p``: An address operand. Similar to ``m``, but used by "load address" 4736 type instructions without touching memory. 4737- ``i``: An integer constant (of target-specific width). Allows either a simple 4738 immediate, or a relocatable value. 4739- ``n``: An integer constant -- *not* including relocatable values. 4740- ``s``: An integer constant, but allowing *only* relocatable values. 4741- ``X``: Allows an operand of any kind, no constraint whatsoever. Typically 4742 useful to pass a label for an asm branch or call. 4743 4744 .. FIXME: but that surely isn't actually okay to jump out of an asm 4745 block without telling llvm about the control transfer???) 4746 4747- ``{register-name}``: Requires exactly the named physical register. 4748 4749Other constraints are target-specific: 4750 4751AArch64: 4752 4753- ``z``: An immediate integer 0. Outputs ``WZR`` or ``XZR``, as appropriate. 4754- ``I``: An immediate integer valid for an ``ADD`` or ``SUB`` instruction, 4755 i.e. 0 to 4095 with optional shift by 12. 4756- ``J``: An immediate integer that, when negated, is valid for an ``ADD`` or 4757 ``SUB`` instruction, i.e. -1 to -4095 with optional left shift by 12. 4758- ``K``: An immediate integer that is valid for the 'bitmask immediate 32' of a 4759 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 32-bit register. 4760- ``L``: An immediate integer that is valid for the 'bitmask immediate 64' of a 4761 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 64-bit register. 4762- ``M``: An immediate integer for use with the ``MOV`` assembly alias on a 4763 32-bit register. This is a superset of ``K``: in addition to the bitmask 4764 immediate, also allows immediate integers which can be loaded with a single 4765 ``MOVZ`` or ``MOVL`` instruction. 4766- ``N``: An immediate integer for use with the ``MOV`` assembly alias on a 4767 64-bit register. This is a superset of ``L``. 4768- ``Q``: Memory address operand must be in a single register (no 4769 offsets). (However, LLVM currently does this for the ``m`` constraint as 4770 well.) 4771- ``r``: A 32 or 64-bit integer register (W* or X*). 4772- ``w``: A 32, 64, or 128-bit floating-point, SIMD or SVE vector register. 4773- ``x``: Like w, but restricted to registers 0 to 15 inclusive. 4774- ``y``: Like w, but restricted to SVE vector registers Z0 to Z7 inclusive. 4775- ``Upl``: One of the low eight SVE predicate registers (P0 to P7) 4776- ``Upa``: Any of the SVE predicate registers (P0 to P15) 4777 4778AMDGPU: 4779 4780- ``r``: A 32 or 64-bit integer register. 4781- ``[0-9]v``: The 32-bit VGPR register, number 0-9. 4782- ``[0-9]s``: The 32-bit SGPR register, number 0-9. 4783- ``[0-9]a``: The 32-bit AGPR register, number 0-9. 4784- ``I``: An integer inline constant in the range from -16 to 64. 4785- ``J``: A 16-bit signed integer constant. 4786- ``A``: An integer or a floating-point inline constant. 4787- ``B``: A 32-bit signed integer constant. 4788- ``C``: A 32-bit unsigned integer constant or an integer inline constant in the range from -16 to 64. 4789- ``DA``: A 64-bit constant that can be split into two "A" constants. 4790- ``DB``: A 64-bit constant that can be split into two "B" constants. 4791 4792All ARM modes: 4793 4794- ``Q``, ``Um``, ``Un``, ``Uq``, ``Us``, ``Ut``, ``Uv``, ``Uy``: Memory address 4795 operand. Treated the same as operand ``m``, at the moment. 4796- ``Te``: An even general-purpose 32-bit integer register: ``r0,r2,...,r12,r14`` 4797- ``To``: An odd general-purpose 32-bit integer register: ``r1,r3,...,r11`` 4798 4799ARM and ARM's Thumb2 mode: 4800 4801- ``j``: An immediate integer between 0 and 65535 (valid for ``MOVW``) 4802- ``I``: An immediate integer valid for a data-processing instruction. 4803- ``J``: An immediate integer between -4095 and 4095. 4804- ``K``: An immediate integer whose bitwise inverse is valid for a 4805 data-processing instruction. (Can be used with template modifier "``B``" to 4806 print the inverted value). 4807- ``L``: An immediate integer whose negation is valid for a data-processing 4808 instruction. (Can be used with template modifier "``n``" to print the negated 4809 value). 4810- ``M``: A power of two or an integer between 0 and 32. 4811- ``N``: Invalid immediate constraint. 4812- ``O``: Invalid immediate constraint. 4813- ``r``: A general-purpose 32-bit integer register (``r0-r15``). 4814- ``l``: In Thumb2 mode, low 32-bit GPR registers (``r0-r7``). In ARM mode, same 4815 as ``r``. 4816- ``h``: In Thumb2 mode, a high 32-bit GPR register (``r8-r15``). In ARM mode, 4817 invalid. 4818- ``w``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4819 ``s0-s31``, ``d0-d31``, or ``q0-q15``, respectively. 4820- ``t``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4821 ``s0-s31``, ``d0-d15``, or ``q0-q7``, respectively. 4822- ``x``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4823 ``s0-s15``, ``d0-d7``, or ``q0-q3``, respectively. 4824 4825ARM's Thumb1 mode: 4826 4827- ``I``: An immediate integer between 0 and 255. 4828- ``J``: An immediate integer between -255 and -1. 4829- ``K``: An immediate integer between 0 and 255, with optional left-shift by 4830 some amount. 4831- ``L``: An immediate integer between -7 and 7. 4832- ``M``: An immediate integer which is a multiple of 4 between 0 and 1020. 4833- ``N``: An immediate integer between 0 and 31. 4834- ``O``: An immediate integer which is a multiple of 4 between -508 and 508. 4835- ``r``: A low 32-bit GPR register (``r0-r7``). 4836- ``l``: A low 32-bit GPR register (``r0-r7``). 4837- ``h``: A high GPR register (``r0-r7``). 4838- ``w``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4839 ``s0-s31``, ``d0-d31``, or ``q0-q15``, respectively. 4840- ``t``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4841 ``s0-s31``, ``d0-d15``, or ``q0-q7``, respectively. 4842- ``x``: A 32, 64, or 128-bit floating-point/SIMD register in the ranges 4843 ``s0-s15``, ``d0-d7``, or ``q0-q3``, respectively. 4844 4845 4846Hexagon: 4847 4848- ``o``, ``v``: A memory address operand, treated the same as constraint ``m``, 4849 at the moment. 4850- ``r``: A 32 or 64-bit register. 4851 4852MSP430: 4853 4854- ``r``: An 8 or 16-bit register. 4855 4856MIPS: 4857 4858- ``I``: An immediate signed 16-bit integer. 4859- ``J``: An immediate integer zero. 4860- ``K``: An immediate unsigned 16-bit integer. 4861- ``L``: An immediate 32-bit integer, where the lower 16 bits are 0. 4862- ``N``: An immediate integer between -65535 and -1. 4863- ``O``: An immediate signed 15-bit integer. 4864- ``P``: An immediate integer between 1 and 65535. 4865- ``m``: A memory address operand. In MIPS-SE mode, allows a base address 4866 register plus 16-bit immediate offset. In MIPS mode, just a base register. 4867- ``R``: A memory address operand. In MIPS-SE mode, allows a base address 4868 register plus a 9-bit signed offset. In MIPS mode, the same as constraint 4869 ``m``. 4870- ``ZC``: A memory address operand, suitable for use in a ``pref``, ``ll``, or 4871 ``sc`` instruction on the given subtarget (details vary). 4872- ``r``, ``d``, ``y``: A 32 or 64-bit GPR register. 4873- ``f``: A 32 or 64-bit FPU register (``F0-F31``), or a 128-bit MSA register 4874 (``W0-W31``). In the case of MSA registers, it is recommended to use the ``w`` 4875 argument modifier for compatibility with GCC. 4876- ``c``: A 32-bit or 64-bit GPR register suitable for indirect jump (always 4877 ``25``). 4878- ``l``: The ``lo`` register, 32 or 64-bit. 4879- ``x``: Invalid. 4880 4881NVPTX: 4882 4883- ``b``: A 1-bit integer register. 4884- ``c`` or ``h``: A 16-bit integer register. 4885- ``r``: A 32-bit integer register. 4886- ``l`` or ``N``: A 64-bit integer register. 4887- ``f``: A 32-bit float register. 4888- ``d``: A 64-bit float register. 4889 4890 4891PowerPC: 4892 4893- ``I``: An immediate signed 16-bit integer. 4894- ``J``: An immediate unsigned 16-bit integer, shifted left 16 bits. 4895- ``K``: An immediate unsigned 16-bit integer. 4896- ``L``: An immediate signed 16-bit integer, shifted left 16 bits. 4897- ``M``: An immediate integer greater than 31. 4898- ``N``: An immediate integer that is an exact power of 2. 4899- ``O``: The immediate integer constant 0. 4900- ``P``: An immediate integer constant whose negation is a signed 16-bit 4901 constant. 4902- ``es``, ``o``, ``Q``, ``Z``, ``Zy``: A memory address operand, currently 4903 treated the same as ``m``. 4904- ``r``: A 32 or 64-bit integer register. 4905- ``b``: A 32 or 64-bit integer register, excluding ``R0`` (that is: 4906 ``R1-R31``). 4907- ``f``: A 32 or 64-bit float register (``F0-F31``), 4908- ``v``: For ``4 x f32`` or ``4 x f64`` types, a 128-bit altivec vector 4909 register (``V0-V31``). 4910 4911- ``y``: Condition register (``CR0-CR7``). 4912- ``wc``: An individual CR bit in a CR register. 4913- ``wa``, ``wd``, ``wf``: Any 128-bit VSX vector register, from the full VSX 4914 register set (overlapping both the floating-point and vector register files). 4915- ``ws``: A 32 or 64-bit floating-point register, from the full VSX register 4916 set. 4917 4918RISC-V: 4919 4920- ``A``: An address operand (using a general-purpose register, without an 4921 offset). 4922- ``I``: A 12-bit signed integer immediate operand. 4923- ``J``: A zero integer immediate operand. 4924- ``K``: A 5-bit unsigned integer immediate operand. 4925- ``f``: A 32- or 64-bit floating-point register (requires F or D extension). 4926- ``r``: A 32- or 64-bit general-purpose register (depending on the platform 4927 ``XLEN``). 4928- ``vr``: A vector register. (requires V extension). 4929- ``vm``: A vector register for masking operand. (requires V extension). 4930 4931Sparc: 4932 4933- ``I``: An immediate 13-bit signed integer. 4934- ``r``: A 32-bit integer register. 4935- ``f``: Any floating-point register on SparcV8, or a floating-point 4936 register in the "low" half of the registers on SparcV9. 4937- ``e``: Any floating-point register. (Same as ``f`` on SparcV8.) 4938 4939SystemZ: 4940 4941- ``I``: An immediate unsigned 8-bit integer. 4942- ``J``: An immediate unsigned 12-bit integer. 4943- ``K``: An immediate signed 16-bit integer. 4944- ``L``: An immediate signed 20-bit integer. 4945- ``M``: An immediate integer 0x7fffffff. 4946- ``Q``: A memory address operand with a base address and a 12-bit immediate 4947 unsigned displacement. 4948- ``R``: A memory address operand with a base address, a 12-bit immediate 4949 unsigned displacement, and an index register. 4950- ``S``: A memory address operand with a base address and a 20-bit immediate 4951 signed displacement. 4952- ``T``: A memory address operand with a base address, a 20-bit immediate 4953 signed displacement, and an index register. 4954- ``r`` or ``d``: A 32, 64, or 128-bit integer register. 4955- ``a``: A 32, 64, or 128-bit integer address register (excludes R0, which in an 4956 address context evaluates as zero). 4957- ``h``: A 32-bit value in the high part of a 64bit data register 4958 (LLVM-specific) 4959- ``f``: A 32, 64, or 128-bit floating-point register. 4960 4961X86: 4962 4963- ``I``: An immediate integer between 0 and 31. 4964- ``J``: An immediate integer between 0 and 64. 4965- ``K``: An immediate signed 8-bit integer. 4966- ``L``: An immediate integer, 0xff or 0xffff or (in 64-bit mode only) 4967 0xffffffff. 4968- ``M``: An immediate integer between 0 and 3. 4969- ``N``: An immediate unsigned 8-bit integer. 4970- ``O``: An immediate integer between 0 and 127. 4971- ``e``: An immediate 32-bit signed integer. 4972- ``Z``: An immediate 32-bit unsigned integer. 4973- ``o``, ``v``: Treated the same as ``m``, at the moment. 4974- ``q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit 4975 ``l`` integer register. On X86-32, this is the ``a``, ``b``, ``c``, and ``d`` 4976 registers, and on X86-64, it is all of the integer registers. 4977- ``Q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit 4978 ``h`` integer register. This is the ``a``, ``b``, ``c``, and ``d`` registers. 4979- ``r`` or ``l``: An 8, 16, 32, or 64-bit integer register. 4980- ``R``: An 8, 16, 32, or 64-bit "legacy" integer register -- one which has 4981 existed since i386, and can be accessed without the REX prefix. 4982- ``f``: A 32, 64, or 80-bit '387 FPU stack pseudo-register. 4983- ``y``: A 64-bit MMX register, if MMX is enabled. 4984- ``x``: If SSE is enabled: a 32 or 64-bit scalar operand, or 128-bit vector 4985 operand in a SSE register. If AVX is also enabled, can also be a 256-bit 4986 vector operand in an AVX register. If AVX-512 is also enabled, can also be a 4987 512-bit vector operand in an AVX512 register, Otherwise, an error. 4988- ``Y``: The same as ``x``, if *SSE2* is enabled, otherwise an error. 4989- ``A``: Special case: allocates EAX first, then EDX, for a single operand (in 4990 32-bit mode, a 64-bit integer operand will get split into two registers). It 4991 is not recommended to use this constraint, as in 64-bit mode, the 64-bit 4992 operand will get allocated only to RAX -- if two 32-bit operands are needed, 4993 you're better off splitting it yourself, before passing it to the asm 4994 statement. 4995 4996XCore: 4997 4998- ``r``: A 32-bit integer register. 4999 5000 5001.. _inline-asm-modifiers: 5002 5003Asm template argument modifiers 5004^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5005 5006In the asm template string, modifiers can be used on the operand reference, like 5007"``${0:n}``". 5008 5009The modifiers are, in general, expected to behave the same way they do in 5010GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C 5011inline asm code which was supported by GCC. A mismatch in behavior between LLVM 5012and GCC likely indicates a bug in LLVM. 5013 5014Target-independent: 5015 5016- ``c``: Print an immediate integer constant unadorned, without 5017 the target-specific immediate punctuation (e.g. no ``$`` prefix). 5018- ``n``: Negate and print immediate integer constant unadorned, without the 5019 target-specific immediate punctuation (e.g. no ``$`` prefix). 5020- ``l``: Print as an unadorned label, without the target-specific label 5021 punctuation (e.g. no ``$`` prefix). 5022 5023AArch64: 5024 5025- ``w``: Print a GPR register with a ``w*`` name instead of ``x*`` name. E.g., 5026 instead of ``x30``, print ``w30``. 5027- ``x``: Print a GPR register with a ``x*`` name. (this is the default, anyhow). 5028- ``b``, ``h``, ``s``, ``d``, ``q``: Print a floating-point/SIMD register with a 5029 ``b*``, ``h*``, ``s*``, ``d*``, or ``q*`` name, rather than the default of 5030 ``v*``. 5031 5032AMDGPU: 5033 5034- ``r``: No effect. 5035 5036ARM: 5037 5038- ``a``: Print an operand as an address (with ``[`` and ``]`` surrounding a 5039 register). 5040- ``P``: No effect. 5041- ``q``: No effect. 5042- ``y``: Print a VFP single-precision register as an indexed double (e.g. print 5043 as ``d4[1]`` instead of ``s9``) 5044- ``B``: Bitwise invert and print an immediate integer constant without ``#`` 5045 prefix. 5046- ``L``: Print the low 16-bits of an immediate integer constant. 5047- ``M``: Print as a register set suitable for ldm/stm. Also prints *all* 5048 register operands subsequent to the specified one (!), so use carefully. 5049- ``Q``: Print the low-order register of a register-pair, or the low-order 5050 register of a two-register operand. 5051- ``R``: Print the high-order register of a register-pair, or the high-order 5052 register of a two-register operand. 5053- ``H``: Print the second register of a register-pair. (On a big-endian system, 5054 ``H`` is equivalent to ``Q``, and on little-endian system, ``H`` is equivalent 5055 to ``R``.) 5056 5057 .. FIXME: H doesn't currently support printing the second register 5058 of a two-register operand. 5059 5060- ``e``: Print the low doubleword register of a NEON quad register. 5061- ``f``: Print the high doubleword register of a NEON quad register. 5062- ``m``: Print the base register of a memory operand without the ``[`` and ``]`` 5063 adornment. 5064 5065Hexagon: 5066 5067- ``L``: Print the second register of a two-register operand. Requires that it 5068 has been allocated consecutively to the first. 5069 5070 .. FIXME: why is it restricted to consecutive ones? And there's 5071 nothing that ensures that happens, is there? 5072 5073- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise 5074 nothing. Used to print 'addi' vs 'add' instructions. 5075 5076MSP430: 5077 5078No additional modifiers. 5079 5080MIPS: 5081 5082- ``X``: Print an immediate integer as hexadecimal 5083- ``x``: Print the low 16 bits of an immediate integer as hexadecimal. 5084- ``d``: Print an immediate integer as decimal. 5085- ``m``: Subtract one and print an immediate integer as decimal. 5086- ``z``: Print $0 if an immediate zero, otherwise print normally. 5087- ``L``: Print the low-order register of a two-register operand, or prints the 5088 address of the low-order word of a double-word memory operand. 5089 5090 .. FIXME: L seems to be missing memory operand support. 5091 5092- ``M``: Print the high-order register of a two-register operand, or prints the 5093 address of the high-order word of a double-word memory operand. 5094 5095 .. FIXME: M seems to be missing memory operand support. 5096 5097- ``D``: Print the second register of a two-register operand, or prints the 5098 second word of a double-word memory operand. (On a big-endian system, ``D`` is 5099 equivalent to ``L``, and on little-endian system, ``D`` is equivalent to 5100 ``M``.) 5101- ``w``: No effect. Provided for compatibility with GCC which requires this 5102 modifier in order to print MSA registers (``W0-W31``) with the ``f`` 5103 constraint. 5104 5105NVPTX: 5106 5107- ``r``: No effect. 5108 5109PowerPC: 5110 5111- ``L``: Print the second register of a two-register operand. Requires that it 5112 has been allocated consecutively to the first. 5113 5114 .. FIXME: why is it restricted to consecutive ones? And there's 5115 nothing that ensures that happens, is there? 5116 5117- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise 5118 nothing. Used to print 'addi' vs 'add' instructions. 5119- ``y``: For a memory operand, prints formatter for a two-register X-form 5120 instruction. (Currently always prints ``r0,OPERAND``). 5121- ``U``: Prints 'u' if the memory operand is an update form, and nothing 5122 otherwise. (NOTE: LLVM does not support update form, so this will currently 5123 always print nothing) 5124- ``X``: Prints 'x' if the memory operand is an indexed form. (NOTE: LLVM does 5125 not support indexed form, so this will currently always print nothing) 5126 5127RISC-V: 5128 5129- ``i``: Print the letter 'i' if the operand is not a register, otherwise print 5130 nothing. Used to print 'addi' vs 'add' instructions, etc. 5131- ``z``: Print the register ``zero`` if an immediate zero, otherwise print 5132 normally. 5133 5134Sparc: 5135 5136- ``r``: No effect. 5137 5138SystemZ: 5139 5140SystemZ implements only ``n``, and does *not* support any of the other 5141target-independent modifiers. 5142 5143X86: 5144 5145- ``c``: Print an unadorned integer or symbol name. (The latter is 5146 target-specific behavior for this typically target-independent modifier). 5147- ``A``: Print a register name with a '``*``' before it. 5148- ``b``: Print an 8-bit register name (e.g. ``al``); do nothing on a memory 5149 operand. 5150- ``h``: Print the upper 8-bit register name (e.g. ``ah``); do nothing on a 5151 memory operand. 5152- ``w``: Print the 16-bit register name (e.g. ``ax``); do nothing on a memory 5153 operand. 5154- ``k``: Print the 32-bit register name (e.g. ``eax``); do nothing on a memory 5155 operand. 5156- ``q``: Print the 64-bit register name (e.g. ``rax``), if 64-bit registers are 5157 available, otherwise the 32-bit register name; do nothing on a memory operand. 5158- ``n``: Negate and print an unadorned integer, or, for operands other than an 5159 immediate integer (e.g. a relocatable symbol expression), print a '-' before 5160 the operand. (The behavior for relocatable symbol expressions is a 5161 target-specific behavior for this typically target-independent modifier) 5162- ``H``: Print a memory reference with additional offset +8. 5163- ``P``: Print a memory reference used as the argument of a call instruction or 5164 used with explicit base reg and index reg as its offset. So it can not use 5165 additional regs to present the memory reference. (E.g. omit ``(rip)``, even 5166 though it's PC-relative.) 5167 5168XCore: 5169 5170No additional modifiers. 5171 5172 5173Inline Asm Metadata 5174^^^^^^^^^^^^^^^^^^^ 5175 5176The call instructions that wrap inline asm nodes may have a 5177"``!srcloc``" MDNode attached to it that contains a list of constant 5178integers. If present, the code generator will use the integer as the 5179location cookie value when report errors through the ``LLVMContext`` 5180error reporting mechanisms. This allows a front-end to correlate backend 5181errors that occur with inline asm back to the source code that produced 5182it. For example: 5183 5184.. code-block:: llvm 5185 5186 call void asm sideeffect "something bad", ""(), !srcloc !42 5187 ... 5188 !42 = !{ i32 1234567 } 5189 5190It is up to the front-end to make sense of the magic numbers it places 5191in the IR. If the MDNode contains multiple constants, the code generator 5192will use the one that corresponds to the line of the asm that the error 5193occurs on. 5194 5195.. _metadata: 5196 5197Metadata 5198======== 5199 5200LLVM IR allows metadata to be attached to instructions and global objects in the 5201program that can convey extra information about the code to the optimizers and 5202code generator. One example application of metadata is source-level 5203debug information. There are two metadata primitives: strings and nodes. 5204 5205Metadata does not have a type, and is not a value. If referenced from a 5206``call`` instruction, it uses the ``metadata`` type. 5207 5208All metadata are identified in syntax by an exclamation point ('``!``'). 5209 5210.. _metadata-string: 5211 5212Metadata Nodes and Metadata Strings 5213----------------------------------- 5214 5215A metadata string is a string surrounded by double quotes. It can 5216contain any character by escaping non-printable characters with 5217"``\xx``" where "``xx``" is the two digit hex code. For example: 5218"``!"test\00"``". 5219 5220Metadata nodes are represented with notation similar to structure 5221constants (a comma separated list of elements, surrounded by braces and 5222preceded by an exclamation point). Metadata nodes can have any values as 5223their operand. For example: 5224 5225.. code-block:: llvm 5226 5227 !{ !"test\00", i32 10} 5228 5229Metadata nodes that aren't uniqued use the ``distinct`` keyword. For example: 5230 5231.. code-block:: text 5232 5233 !0 = distinct !{!"test\00", i32 10} 5234 5235``distinct`` nodes are useful when nodes shouldn't be merged based on their 5236content. They can also occur when transformations cause uniquing collisions 5237when metadata operands change. 5238 5239A :ref:`named metadata <namedmetadatastructure>` is a collection of 5240metadata nodes, which can be looked up in the module symbol table. For 5241example: 5242 5243.. code-block:: llvm 5244 5245 !foo = !{!4, !3} 5246 5247Metadata can be used as function arguments. Here the ``llvm.dbg.value`` 5248intrinsic is using three metadata arguments: 5249 5250.. code-block:: llvm 5251 5252 call void @llvm.dbg.value(metadata !24, metadata !25, metadata !26) 5253 5254Metadata can be attached to an instruction. Here metadata ``!21`` is attached 5255to the ``add`` instruction using the ``!dbg`` identifier: 5256 5257.. code-block:: llvm 5258 5259 %indvar.next = add i64 %indvar, 1, !dbg !21 5260 5261Instructions may not have multiple metadata attachments with the same 5262identifier. 5263 5264Metadata can also be attached to a function or a global variable. Here metadata 5265``!22`` is attached to the ``f1`` and ``f2`` functions, and the globals ``g1`` 5266and ``g2`` using the ``!dbg`` identifier: 5267 5268.. code-block:: llvm 5269 5270 declare !dbg !22 void @f1() 5271 define void @f2() !dbg !22 { 5272 ret void 5273 } 5274 5275 @g1 = global i32 0, !dbg !22 5276 @g2 = external global i32, !dbg !22 5277 5278Unlike instructions, global objects (functions and global variables) may have 5279multiple metadata attachments with the same identifier. 5280 5281A transformation is required to drop any metadata attachment that it does not 5282know or know it can't preserve. Currently there is an exception for metadata 5283attachment to globals for ``!func_sanitize``, ``!type`` and ``!absolute_symbol`` which can't be 5284unconditionally dropped unless the global is itself deleted. 5285 5286Metadata attached to a module using named metadata may not be dropped, with 5287the exception of debug metadata (named metadata with the name ``!llvm.dbg.*``). 5288 5289More information about specific metadata nodes recognized by the 5290optimizers and code generator is found below. 5291 5292.. _specialized-metadata: 5293 5294Specialized Metadata Nodes 5295^^^^^^^^^^^^^^^^^^^^^^^^^^ 5296 5297Specialized metadata nodes are custom data structures in metadata (as opposed 5298to generic tuples). Their fields are labelled, and can be specified in any 5299order. 5300 5301These aren't inherently debug info centric, but currently all the specialized 5302metadata nodes are related to debug info. 5303 5304.. _DICompileUnit: 5305 5306DICompileUnit 5307""""""""""""" 5308 5309``DICompileUnit`` nodes represent a compile unit. The ``enums:``, 5310``retainedTypes:``, ``globals:``, ``imports:`` and ``macros:`` fields are tuples 5311containing the debug info to be emitted along with the compile unit, regardless 5312of code optimizations (some nodes are only emitted if there are references to 5313them from instructions). The ``debugInfoForProfiling:`` field is a boolean 5314indicating whether or not line-table discriminators are updated to provide 5315more-accurate debug info for profiling results. 5316 5317.. code-block:: text 5318 5319 !0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang", 5320 isOptimized: true, flags: "-O2", runtimeVersion: 2, 5321 splitDebugFilename: "abc.debug", emissionKind: FullDebug, 5322 enums: !2, retainedTypes: !3, globals: !4, imports: !5, 5323 macros: !6, dwoId: 0x0abcd) 5324 5325Compile unit descriptors provide the root scope for objects declared in a 5326specific compilation unit. File descriptors are defined using this scope. These 5327descriptors are collected by a named metadata node ``!llvm.dbg.cu``. They keep 5328track of global variables, type information, and imported entities (declarations 5329and namespaces). 5330 5331.. _DIFile: 5332 5333DIFile 5334"""""" 5335 5336``DIFile`` nodes represent files. The ``filename:`` can include slashes. 5337 5338.. code-block:: none 5339 5340 !0 = !DIFile(filename: "path/to/file", directory: "/path/to/dir", 5341 checksumkind: CSK_MD5, 5342 checksum: "000102030405060708090a0b0c0d0e0f") 5343 5344Files are sometimes used in ``scope:`` fields, and are the only valid target 5345for ``file:`` fields. 5346Valid values for ``checksumkind:`` field are: {CSK_None, CSK_MD5, CSK_SHA1, CSK_SHA256} 5347 5348.. _DIBasicType: 5349 5350DIBasicType 5351""""""""""" 5352 5353``DIBasicType`` nodes represent primitive types, such as ``int``, ``bool`` and 5354``float``. ``tag:`` defaults to ``DW_TAG_base_type``. 5355 5356.. code-block:: text 5357 5358 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8, 5359 encoding: DW_ATE_unsigned_char) 5360 !1 = !DIBasicType(tag: DW_TAG_unspecified_type, name: "decltype(nullptr)") 5361 5362The ``encoding:`` describes the details of the type. Usually it's one of the 5363following: 5364 5365.. code-block:: text 5366 5367 DW_ATE_address = 1 5368 DW_ATE_boolean = 2 5369 DW_ATE_float = 4 5370 DW_ATE_signed = 5 5371 DW_ATE_signed_char = 6 5372 DW_ATE_unsigned = 7 5373 DW_ATE_unsigned_char = 8 5374 5375.. _DISubroutineType: 5376 5377DISubroutineType 5378"""""""""""""""" 5379 5380``DISubroutineType`` nodes represent subroutine types. Their ``types:`` field 5381refers to a tuple; the first operand is the return type, while the rest are the 5382types of the formal arguments in order. If the first operand is ``null``, that 5383represents a function with no return value (such as ``void foo() {}`` in C++). 5384 5385.. code-block:: text 5386 5387 !0 = !BasicType(name: "int", size: 32, align: 32, DW_ATE_signed) 5388 !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char) 5389 !2 = !DISubroutineType(types: !{null, !0, !1}) ; void (int, char) 5390 5391.. _DIDerivedType: 5392 5393DIDerivedType 5394""""""""""""" 5395 5396``DIDerivedType`` nodes represent types derived from other types, such as 5397qualified types. 5398 5399.. code-block:: text 5400 5401 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8, 5402 encoding: DW_ATE_unsigned_char) 5403 !1 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !0, size: 32, 5404 align: 32) 5405 5406The following ``tag:`` values are valid: 5407 5408.. code-block:: text 5409 5410 DW_TAG_member = 13 5411 DW_TAG_pointer_type = 15 5412 DW_TAG_reference_type = 16 5413 DW_TAG_typedef = 22 5414 DW_TAG_inheritance = 28 5415 DW_TAG_ptr_to_member_type = 31 5416 DW_TAG_const_type = 38 5417 DW_TAG_friend = 42 5418 DW_TAG_volatile_type = 53 5419 DW_TAG_restrict_type = 55 5420 DW_TAG_atomic_type = 71 5421 DW_TAG_immutable_type = 75 5422 5423.. _DIDerivedTypeMember: 5424 5425``DW_TAG_member`` is used to define a member of a :ref:`composite type 5426<DICompositeType>`. The type of the member is the ``baseType:``. The 5427``offset:`` is the member's bit offset. If the composite type has an ODR 5428``identifier:`` and does not set ``flags: DIFwdDecl``, then the member is 5429uniqued based only on its ``name:`` and ``scope:``. 5430 5431``DW_TAG_inheritance`` and ``DW_TAG_friend`` are used in the ``elements:`` 5432field of :ref:`composite types <DICompositeType>` to describe parents and 5433friends. 5434 5435``DW_TAG_typedef`` is used to provide a name for the ``baseType:``. 5436 5437``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``, 5438``DW_TAG_volatile_type``, ``DW_TAG_restrict_type``, ``DW_TAG_atomic_type`` and 5439``DW_TAG_immutable_type`` are used to qualify the ``baseType:``. 5440 5441Note that the ``void *`` type is expressed as a type derived from NULL. 5442 5443.. _DICompositeType: 5444 5445DICompositeType 5446""""""""""""""" 5447 5448``DICompositeType`` nodes represent types composed of other types, like 5449structures and unions. ``elements:`` points to a tuple of the composed types. 5450 5451If the source language supports ODR, the ``identifier:`` field gives the unique 5452identifier used for type merging between modules. When specified, 5453:ref:`subprogram declarations <DISubprogramDeclaration>` and :ref:`member 5454derived types <DIDerivedTypeMember>` that reference the ODR-type in their 5455``scope:`` change uniquing rules. 5456 5457For a given ``identifier:``, there should only be a single composite type that 5458does not have ``flags: DIFlagFwdDecl`` set. LLVM tools that link modules 5459together will unique such definitions at parse time via the ``identifier:`` 5460field, even if the nodes are ``distinct``. 5461 5462.. code-block:: text 5463 5464 !0 = !DIEnumerator(name: "SixKind", value: 7) 5465 !1 = !DIEnumerator(name: "SevenKind", value: 7) 5466 !2 = !DIEnumerator(name: "NegEightKind", value: -8) 5467 !3 = !DICompositeType(tag: DW_TAG_enumeration_type, name: "Enum", file: !12, 5468 line: 2, size: 32, align: 32, identifier: "_M4Enum", 5469 elements: !{!0, !1, !2}) 5470 5471The following ``tag:`` values are valid: 5472 5473.. code-block:: text 5474 5475 DW_TAG_array_type = 1 5476 DW_TAG_class_type = 2 5477 DW_TAG_enumeration_type = 4 5478 DW_TAG_structure_type = 19 5479 DW_TAG_union_type = 23 5480 5481For ``DW_TAG_array_type``, the ``elements:`` should be :ref:`subrange 5482descriptors <DISubrange>`, each representing the range of subscripts at that 5483level of indexing. The ``DIFlagVector`` flag to ``flags:`` indicates that an 5484array type is a native packed vector. The optional ``dataLocation`` is a 5485DIExpression that describes how to get from an object's address to the actual 5486raw data, if they aren't equivalent. This is only supported for array types, 5487particularly to describe Fortran arrays, which have an array descriptor in 5488addition to the array data. Alternatively it can also be DIVariable which 5489has the address of the actual raw data. The Fortran language supports pointer 5490arrays which can be attached to actual arrays, this attachment between pointer 5491and pointee is called association. The optional ``associated`` is a 5492DIExpression that describes whether the pointer array is currently associated. 5493The optional ``allocated`` is a DIExpression that describes whether the 5494allocatable array is currently allocated. The optional ``rank`` is a 5495DIExpression that describes the rank (number of dimensions) of fortran assumed 5496rank array (rank is known at runtime). 5497 5498For ``DW_TAG_enumeration_type``, the ``elements:`` should be :ref:`enumerator 5499descriptors <DIEnumerator>`, each representing the definition of an enumeration 5500value for the set. All enumeration type descriptors are collected in the 5501``enums:`` field of the :ref:`compile unit <DICompileUnit>`. 5502 5503For ``DW_TAG_structure_type``, ``DW_TAG_class_type``, and 5504``DW_TAG_union_type``, the ``elements:`` should be :ref:`derived types 5505<DIDerivedType>` with ``tag: DW_TAG_member``, ``tag: DW_TAG_inheritance``, or 5506``tag: DW_TAG_friend``; or :ref:`subprograms <DISubprogram>` with 5507``isDefinition: false``. 5508 5509.. _DISubrange: 5510 5511DISubrange 5512"""""""""" 5513 5514``DISubrange`` nodes are the elements for ``DW_TAG_array_type`` variants of 5515:ref:`DICompositeType`. 5516 5517- ``count: -1`` indicates an empty array. 5518- ``count: !10`` describes the count with a :ref:`DILocalVariable`. 5519- ``count: !12`` describes the count with a :ref:`DIGlobalVariable`. 5520 5521.. code-block:: text 5522 5523 !0 = !DISubrange(count: 5, lowerBound: 0) ; array counting from 0 5524 !1 = !DISubrange(count: 5, lowerBound: 1) ; array counting from 1 5525 !2 = !DISubrange(count: -1) ; empty array. 5526 5527 ; Scopes used in rest of example 5528 !6 = !DIFile(filename: "vla.c", directory: "/path/to/file") 5529 !7 = distinct !DICompileUnit(language: DW_LANG_C99, file: !6) 5530 !8 = distinct !DISubprogram(name: "foo", scope: !7, file: !6, line: 5) 5531 5532 ; Use of local variable as count value 5533 !9 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed) 5534 !10 = !DILocalVariable(name: "count", scope: !8, file: !6, line: 42, type: !9) 5535 !11 = !DISubrange(count: !10, lowerBound: 0) 5536 5537 ; Use of global variable as count value 5538 !12 = !DIGlobalVariable(name: "count", scope: !8, file: !6, line: 22, type: !9) 5539 !13 = !DISubrange(count: !12, lowerBound: 0) 5540 5541.. _DIEnumerator: 5542 5543DIEnumerator 5544"""""""""""" 5545 5546``DIEnumerator`` nodes are the elements for ``DW_TAG_enumeration_type`` 5547variants of :ref:`DICompositeType`. 5548 5549.. code-block:: text 5550 5551 !0 = !DIEnumerator(name: "SixKind", value: 7) 5552 !1 = !DIEnumerator(name: "SevenKind", value: 7) 5553 !2 = !DIEnumerator(name: "NegEightKind", value: -8) 5554 5555DITemplateTypeParameter 5556""""""""""""""""""""""" 5557 5558``DITemplateTypeParameter`` nodes represent type parameters to generic source 5559language constructs. They are used (optionally) in :ref:`DICompositeType` and 5560:ref:`DISubprogram` ``templateParams:`` fields. 5561 5562.. code-block:: text 5563 5564 !0 = !DITemplateTypeParameter(name: "Ty", type: !1) 5565 5566DITemplateValueParameter 5567"""""""""""""""""""""""" 5568 5569``DITemplateValueParameter`` nodes represent value parameters to generic source 5570language constructs. ``tag:`` defaults to ``DW_TAG_template_value_parameter``, 5571but if specified can also be set to ``DW_TAG_GNU_template_template_param`` or 5572``DW_TAG_GNU_template_param_pack``. They are used (optionally) in 5573:ref:`DICompositeType` and :ref:`DISubprogram` ``templateParams:`` fields. 5574 5575.. code-block:: text 5576 5577 !0 = !DITemplateValueParameter(name: "Ty", type: !1, value: i32 7) 5578 5579DINamespace 5580""""""""""" 5581 5582``DINamespace`` nodes represent namespaces in the source language. 5583 5584.. code-block:: text 5585 5586 !0 = !DINamespace(name: "myawesomeproject", scope: !1, file: !2, line: 7) 5587 5588.. _DIGlobalVariable: 5589 5590DIGlobalVariable 5591"""""""""""""""" 5592 5593``DIGlobalVariable`` nodes represent global variables in the source language. 5594 5595.. code-block:: text 5596 5597 @foo = global i32, !dbg !0 5598 !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression()) 5599 !1 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !2, 5600 file: !3, line: 7, type: !4, isLocal: true, 5601 isDefinition: false, declaration: !5) 5602 5603 5604DIGlobalVariableExpression 5605"""""""""""""""""""""""""" 5606 5607``DIGlobalVariableExpression`` nodes tie a :ref:`DIGlobalVariable` together 5608with a :ref:`DIExpression`. 5609 5610.. code-block:: text 5611 5612 @lower = global i32, !dbg !0 5613 @upper = global i32, !dbg !1 5614 !0 = !DIGlobalVariableExpression( 5615 var: !2, 5616 expr: !DIExpression(DW_OP_LLVM_fragment, 0, 32) 5617 ) 5618 !1 = !DIGlobalVariableExpression( 5619 var: !2, 5620 expr: !DIExpression(DW_OP_LLVM_fragment, 32, 32) 5621 ) 5622 !2 = !DIGlobalVariable(name: "split64", linkageName: "split64", scope: !3, 5623 file: !4, line: 8, type: !5, declaration: !6) 5624 5625All global variable expressions should be referenced by the `globals:` field of 5626a :ref:`compile unit <DICompileUnit>`. 5627 5628.. _DISubprogram: 5629 5630DISubprogram 5631"""""""""""" 5632 5633``DISubprogram`` nodes represent functions from the source language. A distinct 5634``DISubprogram`` may be attached to a function definition using ``!dbg`` 5635metadata. A unique ``DISubprogram`` may be attached to a function declaration 5636used for call site debug info. The ``retainedNodes:`` field is a list of 5637:ref:`variables <DILocalVariable>` and :ref:`labels <DILabel>` that must be 5638retained, even if their IR counterparts are optimized out of the IR. The 5639``type:`` field must point at an :ref:`DISubroutineType`. 5640 5641.. _DISubprogramDeclaration: 5642 5643When ``isDefinition: false``, subprograms describe a declaration in the type 5644tree as opposed to a definition of a function. If the scope is a composite 5645type with an ODR ``identifier:`` and that does not set ``flags: DIFwdDecl``, 5646then the subprogram declaration is uniqued based only on its ``linkageName:`` 5647and ``scope:``. 5648 5649.. code-block:: text 5650 5651 define void @_Z3foov() !dbg !0 { 5652 ... 5653 } 5654 5655 !0 = distinct !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1, 5656 file: !2, line: 7, type: !3, isLocal: true, 5657 isDefinition: true, scopeLine: 8, 5658 containingType: !4, 5659 virtuality: DW_VIRTUALITY_pure_virtual, 5660 virtualIndex: 10, flags: DIFlagPrototyped, 5661 isOptimized: true, unit: !5, templateParams: !6, 5662 declaration: !7, retainedNodes: !8, 5663 thrownTypes: !9) 5664 5665.. _DILexicalBlock: 5666 5667DILexicalBlock 5668"""""""""""""" 5669 5670``DILexicalBlock`` nodes describe nested blocks within a :ref:`subprogram 5671<DISubprogram>`. The line number and column numbers are used to distinguish 5672two lexical blocks at same depth. They are valid targets for ``scope:`` 5673fields. 5674 5675.. code-block:: text 5676 5677 !0 = distinct !DILexicalBlock(scope: !1, file: !2, line: 7, column: 35) 5678 5679Usually lexical blocks are ``distinct`` to prevent node merging based on 5680operands. 5681 5682.. _DILexicalBlockFile: 5683 5684DILexicalBlockFile 5685"""""""""""""""""" 5686 5687``DILexicalBlockFile`` nodes are used to discriminate between sections of a 5688:ref:`lexical block <DILexicalBlock>`. The ``file:`` field can be changed to 5689indicate textual inclusion, or the ``discriminator:`` field can be used to 5690discriminate between control flow within a single block in the source language. 5691 5692.. code-block:: text 5693 5694 !0 = !DILexicalBlock(scope: !3, file: !4, line: 7, column: 35) 5695 !1 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 0) 5696 !2 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 1) 5697 5698.. _DILocation: 5699 5700DILocation 5701"""""""""" 5702 5703``DILocation`` nodes represent source debug locations. The ``scope:`` field is 5704mandatory, and points at an :ref:`DILexicalBlockFile`, an 5705:ref:`DILexicalBlock`, or an :ref:`DISubprogram`. 5706 5707.. code-block:: text 5708 5709 !0 = !DILocation(line: 2900, column: 42, scope: !1, inlinedAt: !2) 5710 5711.. _DILocalVariable: 5712 5713DILocalVariable 5714""""""""""""""" 5715 5716``DILocalVariable`` nodes represent local variables in the source language. If 5717the ``arg:`` field is set to non-zero, then this variable is a subprogram 5718parameter, and it will be included in the ``retainedNodes:`` field of its 5719:ref:`DISubprogram`. 5720 5721.. code-block:: text 5722 5723 !0 = !DILocalVariable(name: "this", arg: 1, scope: !3, file: !2, line: 7, 5724 type: !3, flags: DIFlagArtificial) 5725 !1 = !DILocalVariable(name: "x", arg: 2, scope: !4, file: !2, line: 7, 5726 type: !3) 5727 !2 = !DILocalVariable(name: "y", scope: !5, file: !2, line: 7, type: !3) 5728 5729.. _DIExpression: 5730 5731DIExpression 5732"""""""""""" 5733 5734``DIExpression`` nodes represent expressions that are inspired by the DWARF 5735expression language. They are used in :ref:`debug intrinsics<dbg_intrinsics>` 5736(such as ``llvm.dbg.declare`` and ``llvm.dbg.value``) to describe how the 5737referenced LLVM variable relates to the source language variable. Debug 5738intrinsics are interpreted left-to-right: start by pushing the value/address 5739operand of the intrinsic onto a stack, then repeatedly push and evaluate 5740opcodes from the DIExpression until the final variable description is produced. 5741 5742The current supported opcode vocabulary is limited: 5743 5744- ``DW_OP_deref`` dereferences the top of the expression stack. 5745- ``DW_OP_plus`` pops the last two entries from the expression stack, adds 5746 them together and appends the result to the expression stack. 5747- ``DW_OP_minus`` pops the last two entries from the expression stack, subtracts 5748 the last entry from the second last entry and appends the result to the 5749 expression stack. 5750- ``DW_OP_plus_uconst, 93`` adds ``93`` to the working expression. 5751- ``DW_OP_LLVM_fragment, 16, 8`` specifies the offset and size (``16`` and ``8`` 5752 here, respectively) of the variable fragment from the working expression. Note 5753 that contrary to DW_OP_bit_piece, the offset is describing the location 5754 within the described source variable. 5755- ``DW_OP_LLVM_convert, 16, DW_ATE_signed`` specifies a bit size and encoding 5756 (``16`` and ``DW_ATE_signed`` here, respectively) to which the top of the 5757 expression stack is to be converted. Maps into a ``DW_OP_convert`` operation 5758 that references a base type constructed from the supplied values. 5759- ``DW_OP_LLVM_tag_offset, tag_offset`` specifies that a memory tag should be 5760 optionally applied to the pointer. The memory tag is derived from the 5761 given tag offset in an implementation-defined manner. 5762- ``DW_OP_swap`` swaps top two stack entries. 5763- ``DW_OP_xderef`` provides extended dereference mechanism. The entry at the top 5764 of the stack is treated as an address. The second stack entry is treated as an 5765 address space identifier. 5766- ``DW_OP_stack_value`` marks a constant value. 5767- ``DW_OP_LLVM_entry_value, N`` may only appear in MIR and at the 5768 beginning of a ``DIExpression``. In DWARF a ``DBG_VALUE`` 5769 instruction binding a ``DIExpression(DW_OP_LLVM_entry_value`` to a 5770 register is lowered to a ``DW_OP_entry_value [reg]``, pushing the 5771 value the register had upon function entry onto the stack. The next 5772 ``(N - 1)`` operations will be part of the ``DW_OP_entry_value`` 5773 block argument. For example, ``!DIExpression(DW_OP_LLVM_entry_value, 5774 1, DW_OP_plus_uconst, 123, DW_OP_stack_value)`` specifies an 5775 expression where the entry value of the debug value instruction's 5776 value/address operand is pushed to the stack, and is added 5777 with 123. Due to framework limitations ``N`` can currently only 5778 be 1. 5779 5780 The operation is introduced by the ``LiveDebugValues`` pass, which 5781 applies it only to function parameters that are unmodified 5782 throughout the function. Support is limited to simple register 5783 location descriptions, or as indirect locations (e.g., when a struct 5784 is passed-by-value to a callee via a pointer to a temporary copy 5785 made in the caller). The entry value op is also introduced by the 5786 ``AsmPrinter`` pass when a call site parameter value 5787 (``DW_AT_call_site_parameter_value``) is represented as entry value 5788 of the parameter. 5789- ``DW_OP_LLVM_arg, N`` is used in debug intrinsics that refer to more than one 5790 value, such as one that calculates the sum of two registers. This is always 5791 used in combination with an ordered list of values, such that 5792 ``DW_OP_LLVM_arg, N`` refers to the ``N``th element in that list. For 5793 example, ``!DIExpression(DW_OP_LLVM_arg, 0, DW_OP_LLVM_arg, 1, DW_OP_minus, 5794 DW_OP_stack_value)`` used with the list ``(%reg1, %reg2)`` would evaluate to 5795 ``%reg1 - reg2``. This list of values should be provided by the containing 5796 intrinsic/instruction. 5797- ``DW_OP_breg`` (or ``DW_OP_bregx``) represents a content on the provided 5798 signed offset of the specified register. The opcode is only generated by the 5799 ``AsmPrinter`` pass to describe call site parameter value which requires an 5800 expression over two registers. 5801- ``DW_OP_push_object_address`` pushes the address of the object which can then 5802 serve as a descriptor in subsequent calculation. This opcode can be used to 5803 calculate bounds of fortran allocatable array which has array descriptors. 5804- ``DW_OP_over`` duplicates the entry currently second in the stack at the top 5805 of the stack. This opcode can be used to calculate bounds of fortran assumed 5806 rank array which has rank known at run time and current dimension number is 5807 implicitly first element of the stack. 5808- ``DW_OP_LLVM_implicit_pointer`` It specifies the dereferenced value. It can 5809 be used to represent pointer variables which are optimized out but the value 5810 it points to is known. This operator is required as it is different than DWARF 5811 operator DW_OP_implicit_pointer in representation and specification (number 5812 and types of operands) and later can not be used as multiple level. 5813 5814.. code-block:: text 5815 5816 IR for "*ptr = 4;" 5817 -------------- 5818 call void @llvm.dbg.value(metadata i32 4, metadata !17, metadata !20) 5819 !17 = !DILocalVariable(name: "ptr1", scope: !12, file: !3, line: 5, 5820 type: !18) 5821 !18 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !19, size: 64) 5822 !19 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed) 5823 !20 = !DIExpression(DW_OP_LLVM_implicit_pointer)) 5824 5825 IR for "**ptr = 4;" 5826 -------------- 5827 call void @llvm.dbg.value(metadata i32 4, metadata !17, metadata !21) 5828 !17 = !DILocalVariable(name: "ptr1", scope: !12, file: !3, line: 5, 5829 type: !18) 5830 !18 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !19, size: 64) 5831 !19 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !20, size: 64) 5832 !20 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed) 5833 !21 = !DIExpression(DW_OP_LLVM_implicit_pointer, 5834 DW_OP_LLVM_implicit_pointer)) 5835 5836DWARF specifies three kinds of simple location descriptions: Register, memory, 5837and implicit location descriptions. Note that a location description is 5838defined over certain ranges of a program, i.e the location of a variable may 5839change over the course of the program. Register and memory location 5840descriptions describe the *concrete location* of a source variable (in the 5841sense that a debugger might modify its value), whereas *implicit locations* 5842describe merely the actual *value* of a source variable which might not exist 5843in registers or in memory (see ``DW_OP_stack_value``). 5844 5845A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect 5846value (the address) of a source variable. The first operand of the intrinsic 5847must be an address of some kind. A DIExpression attached to the intrinsic 5848refines this address to produce a concrete location for the source variable. 5849 5850A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable. 5851The first operand of the intrinsic may be a direct or indirect value. A 5852DIExpression attached to the intrinsic refines the first operand to produce a 5853direct value. For example, if the first operand is an indirect value, it may be 5854necessary to insert ``DW_OP_deref`` into the DIExpression in order to produce a 5855valid debug intrinsic. 5856 5857.. note:: 5858 5859 A DIExpression is interpreted in the same way regardless of which kind of 5860 debug intrinsic it's attached to. 5861 5862.. code-block:: text 5863 5864 !0 = !DIExpression(DW_OP_deref) 5865 !1 = !DIExpression(DW_OP_plus_uconst, 3) 5866 !1 = !DIExpression(DW_OP_constu, 3, DW_OP_plus) 5867 !2 = !DIExpression(DW_OP_bit_piece, 3, 7) 5868 !3 = !DIExpression(DW_OP_deref, DW_OP_constu, 3, DW_OP_plus, DW_OP_LLVM_fragment, 3, 7) 5869 !4 = !DIExpression(DW_OP_constu, 2, DW_OP_swap, DW_OP_xderef) 5870 !5 = !DIExpression(DW_OP_constu, 42, DW_OP_stack_value) 5871 5872DIArgList 5873"""""""""""" 5874 5875``DIArgList`` nodes hold a list of constant or SSA value references. These are 5876used in :ref:`debug intrinsics<dbg_intrinsics>` (currently only in 5877``llvm.dbg.value``) in combination with a ``DIExpression`` that uses the 5878``DW_OP_LLVM_arg`` operator. Because a DIArgList may refer to local values 5879within a function, it must only be used as a function argument, must always be 5880inlined, and cannot appear in named metadata. 5881 5882.. code-block:: text 5883 5884 llvm.dbg.value(metadata !DIArgList(i32 %a, i32 %b), 5885 metadata !16, 5886 metadata !DIExpression(DW_OP_LLVM_arg, 0, DW_OP_LLVM_arg, 1, DW_OP_plus)) 5887 5888DIFlags 5889""""""""""""""" 5890 5891These flags encode various properties of DINodes. 5892 5893The `ExportSymbols` flag marks a class, struct or union whose members 5894may be referenced as if they were defined in the containing class or 5895union. This flag is used to decide whether the DW_AT_export_symbols can 5896be used for the structure type. 5897 5898DIObjCProperty 5899"""""""""""""" 5900 5901``DIObjCProperty`` nodes represent Objective-C property nodes. 5902 5903.. code-block:: text 5904 5905 !3 = !DIObjCProperty(name: "foo", file: !1, line: 7, setter: "setFoo", 5906 getter: "getFoo", attributes: 7, type: !2) 5907 5908DIImportedEntity 5909"""""""""""""""" 5910 5911``DIImportedEntity`` nodes represent entities (such as modules) imported into a 5912compile unit. The ``elements`` field is a list of renamed entities (such as 5913variables and subprograms) in the imported entity (such as module). 5914 5915.. code-block:: text 5916 5917 !2 = !DIImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0, 5918 entity: !1, line: 7, elements: !3) 5919 !3 = !{!4} 5920 !4 = !DIImportedEntity(tag: DW_TAG_imported_declaration, name: "bar", scope: !0, 5921 entity: !5, line: 7) 5922 5923DIMacro 5924""""""" 5925 5926``DIMacro`` nodes represent definition or undefinition of a macro identifiers. 5927The ``name:`` field is the macro identifier, followed by macro parameters when 5928defining a function-like macro, and the ``value`` field is the token-string 5929used to expand the macro identifier. 5930 5931.. code-block:: text 5932 5933 !2 = !DIMacro(macinfo: DW_MACINFO_define, line: 7, name: "foo(x)", 5934 value: "((x) + 1)") 5935 !3 = !DIMacro(macinfo: DW_MACINFO_undef, line: 30, name: "foo") 5936 5937DIMacroFile 5938""""""""""" 5939 5940``DIMacroFile`` nodes represent inclusion of source files. 5941The ``nodes:`` field is a list of ``DIMacro`` and ``DIMacroFile`` nodes that 5942appear in the included source file. 5943 5944.. code-block:: text 5945 5946 !2 = !DIMacroFile(macinfo: DW_MACINFO_start_file, line: 7, file: !2, 5947 nodes: !3) 5948 5949.. _DILabel: 5950 5951DILabel 5952""""""" 5953 5954``DILabel`` nodes represent labels within a :ref:`DISubprogram`. All fields of 5955a ``DILabel`` are mandatory. The ``scope:`` field must be one of either a 5956:ref:`DILexicalBlockFile`, a :ref:`DILexicalBlock`, or a :ref:`DISubprogram`. 5957The ``name:`` field is the label identifier. The ``file:`` field is the 5958:ref:`DIFile` the label is present in. The ``line:`` field is the source line 5959within the file where the label is declared. 5960 5961.. code-block:: text 5962 5963 !2 = !DILabel(scope: !0, name: "foo", file: !1, line: 7) 5964 5965'``tbaa``' Metadata 5966^^^^^^^^^^^^^^^^^^^ 5967 5968In LLVM IR, memory does not have types, so LLVM's own type system is not 5969suitable for doing type based alias analysis (TBAA). Instead, metadata is 5970added to the IR to describe a type system of a higher level language. This 5971can be used to implement C/C++ strict type aliasing rules, but it can also 5972be used to implement custom alias analysis behavior for other languages. 5973 5974This description of LLVM's TBAA system is broken into two parts: 5975:ref:`Semantics<tbaa_node_semantics>` talks about high level issues, and 5976:ref:`Representation<tbaa_node_representation>` talks about the metadata 5977encoding of various entities. 5978 5979It is always possible to trace any TBAA node to a "root" TBAA node (details 5980in the :ref:`Representation<tbaa_node_representation>` section). TBAA 5981nodes with different roots have an unknown aliasing relationship, and LLVM 5982conservatively infers ``MayAlias`` between them. The rules mentioned in 5983this section only pertain to TBAA nodes living under the same root. 5984 5985.. _tbaa_node_semantics: 5986 5987Semantics 5988""""""""" 5989 5990The TBAA metadata system, referred to as "struct path TBAA" (not to be 5991confused with ``tbaa.struct``), consists of the following high level 5992concepts: *Type Descriptors*, further subdivided into scalar type 5993descriptors and struct type descriptors; and *Access Tags*. 5994 5995**Type descriptors** describe the type system of the higher level language 5996being compiled. **Scalar type descriptors** describe types that do not 5997contain other types. Each scalar type has a parent type, which must also 5998be a scalar type or the TBAA root. Via this parent relation, scalar types 5999within a TBAA root form a tree. **Struct type descriptors** denote types 6000that contain a sequence of other type descriptors, at known offsets. These 6001contained type descriptors can either be struct type descriptors themselves 6002or scalar type descriptors. 6003 6004**Access tags** are metadata nodes attached to load and store instructions. 6005Access tags use type descriptors to describe the *location* being accessed 6006in terms of the type system of the higher level language. Access tags are 6007tuples consisting of a base type, an access type and an offset. The base 6008type is a scalar type descriptor or a struct type descriptor, the access 6009type is a scalar type descriptor, and the offset is a constant integer. 6010 6011The access tag ``(BaseTy, AccessTy, Offset)`` can describe one of two 6012things: 6013 6014 * If ``BaseTy`` is a struct type, the tag describes a memory access (load 6015 or store) of a value of type ``AccessTy`` contained in the struct type 6016 ``BaseTy`` at offset ``Offset``. 6017 6018 * If ``BaseTy`` is a scalar type, ``Offset`` must be 0 and ``BaseTy`` and 6019 ``AccessTy`` must be the same; and the access tag describes a scalar 6020 access with scalar type ``AccessTy``. 6021 6022We first define an ``ImmediateParent`` relation on ``(BaseTy, Offset)`` 6023tuples this way: 6024 6025 * If ``BaseTy`` is a scalar type then ``ImmediateParent(BaseTy, 0)`` is 6026 ``(ParentTy, 0)`` where ``ParentTy`` is the parent of the scalar type as 6027 described in the TBAA metadata. ``ImmediateParent(BaseTy, Offset)`` is 6028 undefined if ``Offset`` is non-zero. 6029 6030 * If ``BaseTy`` is a struct type then ``ImmediateParent(BaseTy, Offset)`` 6031 is ``(NewTy, NewOffset)`` where ``NewTy`` is the type contained in 6032 ``BaseTy`` at offset ``Offset`` and ``NewOffset`` is ``Offset`` adjusted 6033 to be relative within that inner type. 6034 6035A memory access with an access tag ``(BaseTy1, AccessTy1, Offset1)`` 6036aliases a memory access with an access tag ``(BaseTy2, AccessTy2, 6037Offset2)`` if either ``(BaseTy1, Offset1)`` is reachable from ``(Base2, 6038Offset2)`` via the ``Parent`` relation or vice versa. 6039 6040As a concrete example, the type descriptor graph for the following program 6041 6042.. code-block:: c 6043 6044 struct Inner { 6045 int i; // offset 0 6046 float f; // offset 4 6047 }; 6048 6049 struct Outer { 6050 float f; // offset 0 6051 double d; // offset 4 6052 struct Inner inner_a; // offset 12 6053 }; 6054 6055 void f(struct Outer* outer, struct Inner* inner, float* f, int* i, char* c) { 6056 outer->f = 0; // tag0: (OuterStructTy, FloatScalarTy, 0) 6057 outer->inner_a.i = 0; // tag1: (OuterStructTy, IntScalarTy, 12) 6058 outer->inner_a.f = 0.0; // tag2: (OuterStructTy, FloatScalarTy, 16) 6059 *f = 0.0; // tag3: (FloatScalarTy, FloatScalarTy, 0) 6060 } 6061 6062is (note that in C and C++, ``char`` can be used to access any arbitrary 6063type): 6064 6065.. code-block:: text 6066 6067 Root = "TBAA Root" 6068 CharScalarTy = ("char", Root, 0) 6069 FloatScalarTy = ("float", CharScalarTy, 0) 6070 DoubleScalarTy = ("double", CharScalarTy, 0) 6071 IntScalarTy = ("int", CharScalarTy, 0) 6072 InnerStructTy = {"Inner" (IntScalarTy, 0), (FloatScalarTy, 4)} 6073 OuterStructTy = {"Outer", (FloatScalarTy, 0), (DoubleScalarTy, 4), 6074 (InnerStructTy, 12)} 6075 6076 6077with (e.g.) ``ImmediateParent(OuterStructTy, 12)`` = ``(InnerStructTy, 60780)``, ``ImmediateParent(InnerStructTy, 0)`` = ``(IntScalarTy, 0)``, and 6079``ImmediateParent(IntScalarTy, 0)`` = ``(CharScalarTy, 0)``. 6080 6081.. _tbaa_node_representation: 6082 6083Representation 6084"""""""""""""" 6085 6086The root node of a TBAA type hierarchy is an ``MDNode`` with 0 operands or 6087with exactly one ``MDString`` operand. 6088 6089Scalar type descriptors are represented as an ``MDNode`` s with two 6090operands. The first operand is an ``MDString`` denoting the name of the 6091struct type. LLVM does not assign meaning to the value of this operand, it 6092only cares about it being an ``MDString``. The second operand is an 6093``MDNode`` which points to the parent for said scalar type descriptor, 6094which is either another scalar type descriptor or the TBAA root. Scalar 6095type descriptors can have an optional third argument, but that must be the 6096constant integer zero. 6097 6098Struct type descriptors are represented as ``MDNode`` s with an odd number 6099of operands greater than 1. The first operand is an ``MDString`` denoting 6100the name of the struct type. Like in scalar type descriptors the actual 6101value of this name operand is irrelevant to LLVM. After the name operand, 6102the struct type descriptors have a sequence of alternating ``MDNode`` and 6103``ConstantInt`` operands. With N starting from 1, the 2N - 1 th operand, 6104an ``MDNode``, denotes a contained field, and the 2N th operand, a 6105``ConstantInt``, is the offset of the said contained field. The offsets 6106must be in non-decreasing order. 6107 6108Access tags are represented as ``MDNode`` s with either 3 or 4 operands. 6109The first operand is an ``MDNode`` pointing to the node representing the 6110base type. The second operand is an ``MDNode`` pointing to the node 6111representing the access type. The third operand is a ``ConstantInt`` that 6112states the offset of the access. If a fourth field is present, it must be 6113a ``ConstantInt`` valued at 0 or 1. If it is 1 then the access tag states 6114that the location being accessed is "constant" (meaning 6115``pointsToConstantMemory`` should return true; see `other useful 6116AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_). The TBAA root of 6117the access type and the base type of an access tag must be the same, and 6118that is the TBAA root of the access tag. 6119 6120'``tbaa.struct``' Metadata 6121^^^^^^^^^^^^^^^^^^^^^^^^^^ 6122 6123The :ref:`llvm.memcpy <int_memcpy>` is often used to implement 6124aggregate assignment operations in C and similar languages, however it 6125is defined to copy a contiguous region of memory, which is more than 6126strictly necessary for aggregate types which contain holes due to 6127padding. Also, it doesn't contain any TBAA information about the fields 6128of the aggregate. 6129 6130``!tbaa.struct`` metadata can describe which memory subregions in a 6131memcpy are padding and what the TBAA tags of the struct are. 6132 6133The current metadata format is very simple. ``!tbaa.struct`` metadata 6134nodes are a list of operands which are in conceptual groups of three. 6135For each group of three, the first operand gives the byte offset of a 6136field in bytes, the second gives its size in bytes, and the third gives 6137its tbaa tag. e.g.: 6138 6139.. code-block:: llvm 6140 6141 !4 = !{ i64 0, i64 4, !1, i64 8, i64 4, !2 } 6142 6143This describes a struct with two fields. The first is at offset 0 bytes 6144with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes 6145and has size 4 bytes and has tbaa tag !2. 6146 6147Note that the fields need not be contiguous. In this example, there is a 61484 byte gap between the two fields. This gap represents padding which 6149does not carry useful data and need not be preserved. 6150 6151'``noalias``' and '``alias.scope``' Metadata 6152^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6153 6154``noalias`` and ``alias.scope`` metadata provide the ability to specify generic 6155noalias memory-access sets. This means that some collection of memory access 6156instructions (loads, stores, memory-accessing calls, etc.) that carry 6157``noalias`` metadata can specifically be specified not to alias with some other 6158collection of memory access instructions that carry ``alias.scope`` metadata. 6159Each type of metadata specifies a list of scopes where each scope has an id and 6160a domain. 6161 6162When evaluating an aliasing query, if for some domain, the set 6163of scopes with that domain in one instruction's ``alias.scope`` list is a 6164subset of (or equal to) the set of scopes for that domain in another 6165instruction's ``noalias`` list, then the two memory accesses are assumed not to 6166alias. 6167 6168Because scopes in one domain don't affect scopes in other domains, separate 6169domains can be used to compose multiple independent noalias sets. This is 6170used for example during inlining. As the noalias function parameters are 6171turned into noalias scope metadata, a new domain is used every time the 6172function is inlined. 6173 6174The metadata identifying each domain is itself a list containing one or two 6175entries. The first entry is the name of the domain. Note that if the name is a 6176string then it can be combined across functions and translation units. A 6177self-reference can be used to create globally unique domain names. A 6178descriptive string may optionally be provided as a second list entry. 6179 6180The metadata identifying each scope is also itself a list containing two or 6181three entries. The first entry is the name of the scope. Note that if the name 6182is a string then it can be combined across functions and translation units. A 6183self-reference can be used to create globally unique scope names. A metadata 6184reference to the scope's domain is the second entry. A descriptive string may 6185optionally be provided as a third list entry. 6186 6187For example, 6188 6189.. code-block:: llvm 6190 6191 ; Two scope domains: 6192 !0 = !{!0} 6193 !1 = !{!1} 6194 6195 ; Some scopes in these domains: 6196 !2 = !{!2, !0} 6197 !3 = !{!3, !0} 6198 !4 = !{!4, !1} 6199 6200 ; Some scope lists: 6201 !5 = !{!4} ; A list containing only scope !4 6202 !6 = !{!4, !3, !2} 6203 !7 = !{!3} 6204 6205 ; These two instructions don't alias: 6206 %0 = load float, ptr %c, align 4, !alias.scope !5 6207 store float %0, ptr %arrayidx.i, align 4, !noalias !5 6208 6209 ; These two instructions also don't alias (for domain !1, the set of scopes 6210 ; in the !alias.scope equals that in the !noalias list): 6211 %2 = load float, ptr %c, align 4, !alias.scope !5 6212 store float %2, ptr %arrayidx.i2, align 4, !noalias !6 6213 6214 ; These two instructions may alias (for domain !0, the set of scopes in 6215 ; the !noalias list is not a superset of, or equal to, the scopes in the 6216 ; !alias.scope list): 6217 %2 = load float, ptr %c, align 4, !alias.scope !6 6218 store float %0, ptr %arrayidx.i, align 4, !noalias !7 6219 6220'``fpmath``' Metadata 6221^^^^^^^^^^^^^^^^^^^^^ 6222 6223``fpmath`` metadata may be attached to any instruction of floating-point 6224type. It can be used to express the maximum acceptable error in the 6225result of that instruction, in ULPs, thus potentially allowing the 6226compiler to use a more efficient but less accurate method of computing 6227it. ULP is defined as follows: 6228 6229 If ``x`` is a real number that lies between two finite consecutive 6230 floating-point numbers ``a`` and ``b``, without being equal to one 6231 of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the 6232 distance between the two non-equal finite floating-point numbers 6233 nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``. 6234 6235The metadata node shall consist of a single positive float type number 6236representing the maximum relative error, for example: 6237 6238.. code-block:: llvm 6239 6240 !0 = !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs 6241 6242.. _range-metadata: 6243 6244'``range``' Metadata 6245^^^^^^^^^^^^^^^^^^^^ 6246 6247``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of 6248integer types. It expresses the possible ranges the loaded value or the value 6249returned by the called function at this call site is in. If the loaded or 6250returned value is not in the specified range, the behavior is undefined. The 6251ranges are represented with a flattened list of integers. The loaded value or 6252the value returned is known to be in the union of the ranges defined by each 6253consecutive pair. Each pair has the following properties: 6254 6255- The type must match the type loaded by the instruction. 6256- The pair ``a,b`` represents the range ``[a,b)``. 6257- Both ``a`` and ``b`` are constants. 6258- The range is allowed to wrap. 6259- The range should not represent the full or empty set. That is, 6260 ``a!=b``. 6261 6262In addition, the pairs must be in signed order of the lower bound and 6263they must be non-contiguous. 6264 6265Examples: 6266 6267.. code-block:: llvm 6268 6269 %a = load i8, ptr %x, align 1, !range !0 ; Can only be 0 or 1 6270 %b = load i8, ptr %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1 6271 %c = call i8 @foo(), !range !2 ; Can only be 0, 1, 3, 4 or 5 6272 %d = invoke i8 @bar() to label %cont 6273 unwind label %lpad, !range !3 ; Can only be -2, -1, 3, 4 or 5 6274 ... 6275 !0 = !{ i8 0, i8 2 } 6276 !1 = !{ i8 255, i8 2 } 6277 !2 = !{ i8 0, i8 2, i8 3, i8 6 } 6278 !3 = !{ i8 -2, i8 0, i8 3, i8 6 } 6279 6280'``absolute_symbol``' Metadata 6281^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6282 6283``absolute_symbol`` metadata may be attached to a global variable 6284declaration. It marks the declaration as a reference to an absolute symbol, 6285which causes the backend to use absolute relocations for the symbol even 6286in position independent code, and expresses the possible ranges that the 6287global variable's *address* (not its value) is in, in the same format as 6288``range`` metadata, with the extension that the pair ``all-ones,all-ones`` 6289may be used to represent the full set. 6290 6291Example (assuming 64-bit pointers): 6292 6293.. code-block:: llvm 6294 6295 @a = external global i8, !absolute_symbol !0 ; Absolute symbol in range [0,256) 6296 @b = external global i8, !absolute_symbol !1 ; Absolute symbol in range [0,2^64) 6297 6298 ... 6299 !0 = !{ i64 0, i64 256 } 6300 !1 = !{ i64 -1, i64 -1 } 6301 6302'``callees``' Metadata 6303^^^^^^^^^^^^^^^^^^^^^^ 6304 6305``callees`` metadata may be attached to indirect call sites. If ``callees`` 6306metadata is attached to a call site, and any callee is not among the set of 6307functions provided by the metadata, the behavior is undefined. The intent of 6308this metadata is to facilitate optimizations such as indirect-call promotion. 6309For example, in the code below, the call instruction may only target the 6310``add`` or ``sub`` functions: 6311 6312.. code-block:: llvm 6313 6314 %result = call i64 %binop(i64 %x, i64 %y), !callees !0 6315 6316 ... 6317 !0 = !{ptr @add, ptr @sub} 6318 6319'``callback``' Metadata 6320^^^^^^^^^^^^^^^^^^^^^^^ 6321 6322``callback`` metadata may be attached to a function declaration, or definition. 6323(Call sites are excluded only due to the lack of a use case.) For ease of 6324exposition, we'll refer to the function annotated w/ metadata as a broker 6325function. The metadata describes how the arguments of a call to the broker are 6326in turn passed to the callback function specified by the metadata. Thus, the 6327``callback`` metadata provides a partial description of a call site inside the 6328broker function with regards to the arguments of a call to the broker. The only 6329semantic restriction on the broker function itself is that it is not allowed to 6330inspect or modify arguments referenced in the ``callback`` metadata as 6331pass-through to the callback function. 6332 6333The broker is not required to actually invoke the callback function at runtime. 6334However, the assumptions about not inspecting or modifying arguments that would 6335be passed to the specified callback function still hold, even if the callback 6336function is not dynamically invoked. The broker is allowed to invoke the 6337callback function more than once per invocation of the broker. The broker is 6338also allowed to invoke (directly or indirectly) the function passed as a 6339callback through another use. Finally, the broker is also allowed to relay the 6340callback callee invocation to a different thread. 6341 6342The metadata is structured as follows: At the outer level, ``callback`` 6343metadata is a list of ``callback`` encodings. Each encoding starts with a 6344constant ``i64`` which describes the argument position of the callback function 6345in the call to the broker. The following elements, except the last, describe 6346what arguments are passed to the callback function. Each element is again an 6347``i64`` constant identifying the argument of the broker that is passed through, 6348or ``i64 -1`` to indicate an unknown or inspected argument. The order in which 6349they are listed has to be the same in which they are passed to the callback 6350callee. The last element of the encoding is a boolean which specifies how 6351variadic arguments of the broker are handled. If it is true, all variadic 6352arguments of the broker are passed through to the callback function *after* the 6353arguments encoded explicitly before. 6354 6355In the code below, the ``pthread_create`` function is marked as a broker 6356through the ``!callback !1`` metadata. In the example, there is only one 6357callback encoding, namely ``!2``, associated with the broker. This encoding 6358identifies the callback function as the second argument of the broker (``i64 63592``) and the sole argument of the callback function as the third one of the 6360broker function (``i64 3``). 6361 6362.. FIXME why does the llvm-sphinx-docs builder give a highlighting 6363 error if the below is set to highlight as 'llvm', despite that we 6364 have misc.highlighting_failure set? 6365 6366.. code-block:: text 6367 6368 declare !callback !1 dso_local i32 @pthread_create(ptr, ptr, ptr, ptr) 6369 6370 ... 6371 !2 = !{i64 2, i64 3, i1 false} 6372 !1 = !{!2} 6373 6374Another example is shown below. The callback callee is the second argument of 6375the ``__kmpc_fork_call`` function (``i64 2``). The callee is given two unknown 6376values (each identified by a ``i64 -1``) and afterwards all 6377variadic arguments that are passed to the ``__kmpc_fork_call`` call (due to the 6378final ``i1 true``). 6379 6380.. FIXME why does the llvm-sphinx-docs builder give a highlighting 6381 error if the below is set to highlight as 'llvm', despite that we 6382 have misc.highlighting_failure set? 6383 6384.. code-block:: text 6385 6386 declare !callback !0 dso_local void @__kmpc_fork_call(ptr, i32, ptr, ...) 6387 6388 ... 6389 !1 = !{i64 2, i64 -1, i64 -1, i1 true} 6390 !0 = !{!1} 6391 6392'``exclude``' Metadata 6393^^^^^^^^^^^^^^^^^^^^^^ 6394 6395``exclude`` metadata may be attached to a global variable to signify that its 6396section should not be included in the final executable or shared library. This 6397option is only valid for global variables with an explicit section targeting ELF 6398or COFF. This is done using the ``SHF_EXCLUDE`` flag on ELF targets and the 6399``IMAGE_SCN_LNK_REMOVE`` and ``IMAGE_SCN_MEM_DISCARDABLE`` flags for COFF 6400targets. Additionally, this metadata is only used as a flag, so the associated 6401node must be empty. The explicit section should not conflict with any other 6402sections that the user does not want removed after linking. 6403 6404.. code-block:: text 6405 6406 @object = private constant [1 x i8] c"\00", section ".foo" !exclude !0 6407 6408 ... 6409 !0 = !{} 6410 6411'``unpredictable``' Metadata 6412^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6413 6414``unpredictable`` metadata may be attached to any branch or switch 6415instruction. It can be used to express the unpredictability of control 6416flow. Similar to the llvm.expect intrinsic, it may be used to alter 6417optimizations related to compare and branch instructions. The metadata 6418is treated as a boolean value; if it exists, it signals that the branch 6419or switch that it is attached to is completely unpredictable. 6420 6421.. _md_dereferenceable: 6422 6423'``dereferenceable``' Metadata 6424^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6425 6426The existence of the ``!dereferenceable`` metadata on the instruction 6427tells the optimizer that the value loaded is known to be dereferenceable. 6428The number of bytes known to be dereferenceable is specified by the integer 6429value in the metadata node. This is analogous to the ''dereferenceable'' 6430attribute on parameters and return values. 6431 6432.. _md_dereferenceable_or_null: 6433 6434'``dereferenceable_or_null``' Metadata 6435^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6436 6437The existence of the ``!dereferenceable_or_null`` metadata on the 6438instruction tells the optimizer that the value loaded is known to be either 6439dereferenceable or null. 6440The number of bytes known to be dereferenceable is specified by the integer 6441value in the metadata node. This is analogous to the ''dereferenceable_or_null'' 6442attribute on parameters and return values. 6443 6444.. _llvm.loop: 6445 6446'``llvm.loop``' 6447^^^^^^^^^^^^^^^ 6448 6449It is sometimes useful to attach information to loop constructs. Currently, 6450loop metadata is implemented as metadata attached to the branch instruction 6451in the loop latch block. The loop metadata node is a list of 6452other metadata nodes, each representing a property of the loop. Usually, 6453the first item of the property node is a string. For example, the 6454``llvm.loop.unroll.count`` suggests an unroll factor to the loop 6455unroller: 6456 6457.. code-block:: llvm 6458 6459 br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0 6460 ... 6461 !0 = !{!0, !1, !2} 6462 !1 = !{!"llvm.loop.unroll.enable"} 6463 !2 = !{!"llvm.loop.unroll.count", i32 4} 6464 6465For legacy reasons, the first item of a loop metadata node must be a 6466reference to itself. Before the advent of the 'distinct' keyword, this 6467forced the preservation of otherwise identical metadata nodes. Since 6468the loop-metadata node can be attached to multiple nodes, the 'distinct' 6469keyword has become unnecessary. 6470 6471Prior to the property nodes, one or two ``DILocation`` (debug location) 6472nodes can be present in the list. The first, if present, identifies the 6473source-code location where the loop begins. The second, if present, 6474identifies the source-code location where the loop ends. 6475 6476Loop metadata nodes cannot be used as unique identifiers. They are 6477neither persistent for the same loop through transformations nor 6478necessarily unique to just one loop. 6479 6480'``llvm.loop.disable_nonforced``' 6481^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6482 6483This metadata disables all optional loop transformations unless 6484explicitly instructed using other transformation metadata such as 6485``llvm.loop.unroll.enable``. That is, no heuristic will try to determine 6486whether a transformation is profitable. The purpose is to avoid that the 6487loop is transformed to a different loop before an explicitly requested 6488(forced) transformation is applied. For instance, loop fusion can make 6489other transformations impossible. Mandatory loop canonicalizations such 6490as loop rotation are still applied. 6491 6492It is recommended to use this metadata in addition to any llvm.loop.* 6493transformation directive. Also, any loop should have at most one 6494directive applied to it (and a sequence of transformations built using 6495followup-attributes). Otherwise, which transformation will be applied 6496depends on implementation details such as the pass pipeline order. 6497 6498See :ref:`transformation-metadata` for details. 6499 6500'``llvm.loop.vectorize``' and '``llvm.loop.interleave``' 6501^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6502 6503Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are 6504used to control per-loop vectorization and interleaving parameters such as 6505vectorization width and interleave count. These metadata should be used in 6506conjunction with ``llvm.loop`` loop identification metadata. The 6507``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only 6508optimization hints and the optimizer will only interleave and vectorize loops if 6509it believes it is safe to do so. The ``llvm.loop.parallel_accesses`` metadata 6510which contains information about loop-carried memory dependencies can be helpful 6511in determining the safety of these transformations. 6512 6513'``llvm.loop.interleave.count``' Metadata 6514^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6515 6516This metadata suggests an interleave count to the loop interleaver. 6517The first operand is the string ``llvm.loop.interleave.count`` and the 6518second operand is an integer specifying the interleave count. For 6519example: 6520 6521.. code-block:: llvm 6522 6523 !0 = !{!"llvm.loop.interleave.count", i32 4} 6524 6525Note that setting ``llvm.loop.interleave.count`` to 1 disables interleaving 6526multiple iterations of the loop. If ``llvm.loop.interleave.count`` is set to 0 6527then the interleave count will be determined automatically. 6528 6529'``llvm.loop.vectorize.enable``' Metadata 6530^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6531 6532This metadata selectively enables or disables vectorization for the loop. The 6533first operand is the string ``llvm.loop.vectorize.enable`` and the second operand 6534is a bit. If the bit operand value is 1 vectorization is enabled. A value of 65350 disables vectorization: 6536 6537.. code-block:: llvm 6538 6539 !0 = !{!"llvm.loop.vectorize.enable", i1 0} 6540 !1 = !{!"llvm.loop.vectorize.enable", i1 1} 6541 6542'``llvm.loop.vectorize.predicate.enable``' Metadata 6543^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6544 6545This metadata selectively enables or disables creating predicated instructions 6546for the loop, which can enable folding of the scalar epilogue loop into the 6547main loop. The first operand is the string 6548``llvm.loop.vectorize.predicate.enable`` and the second operand is a bit. If 6549the bit operand value is 1 vectorization is enabled. A value of 0 disables 6550vectorization: 6551 6552.. code-block:: llvm 6553 6554 !0 = !{!"llvm.loop.vectorize.predicate.enable", i1 0} 6555 !1 = !{!"llvm.loop.vectorize.predicate.enable", i1 1} 6556 6557'``llvm.loop.vectorize.scalable.enable``' Metadata 6558^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6559 6560This metadata selectively enables or disables scalable vectorization for the 6561loop, and only has any effect if vectorization for the loop is already enabled. 6562The first operand is the string ``llvm.loop.vectorize.scalable.enable`` 6563and the second operand is a bit. If the bit operand value is 1 scalable 6564vectorization is enabled, whereas a value of 0 reverts to the default fixed 6565width vectorization: 6566 6567.. code-block:: llvm 6568 6569 !0 = !{!"llvm.loop.vectorize.scalable.enable", i1 0} 6570 !1 = !{!"llvm.loop.vectorize.scalable.enable", i1 1} 6571 6572'``llvm.loop.vectorize.width``' Metadata 6573^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6574 6575This metadata sets the target width of the vectorizer. The first 6576operand is the string ``llvm.loop.vectorize.width`` and the second 6577operand is an integer specifying the width. For example: 6578 6579.. code-block:: llvm 6580 6581 !0 = !{!"llvm.loop.vectorize.width", i32 4} 6582 6583Note that setting ``llvm.loop.vectorize.width`` to 1 disables 6584vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to 65850 or if the loop does not have this metadata the width will be 6586determined automatically. 6587 6588'``llvm.loop.vectorize.followup_vectorized``' Metadata 6589^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6590 6591This metadata defines which loop attributes the vectorized loop will 6592have. See :ref:`transformation-metadata` for details. 6593 6594'``llvm.loop.vectorize.followup_epilogue``' Metadata 6595^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6596 6597This metadata defines which loop attributes the epilogue will have. The 6598epilogue is not vectorized and is executed when either the vectorized 6599loop is not known to preserve semantics (because e.g., it processes two 6600arrays that are found to alias by a runtime check) or for the last 6601iterations that do not fill a complete set of vector lanes. See 6602:ref:`Transformation Metadata <transformation-metadata>` for details. 6603 6604'``llvm.loop.vectorize.followup_all``' Metadata 6605^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6606 6607Attributes in the metadata will be added to both the vectorized and 6608epilogue loop. 6609See :ref:`Transformation Metadata <transformation-metadata>` for details. 6610 6611'``llvm.loop.unroll``' 6612^^^^^^^^^^^^^^^^^^^^^^ 6613 6614Metadata prefixed with ``llvm.loop.unroll`` are loop unrolling 6615optimization hints such as the unroll factor. ``llvm.loop.unroll`` 6616metadata should be used in conjunction with ``llvm.loop`` loop 6617identification metadata. The ``llvm.loop.unroll`` metadata are only 6618optimization hints and the unrolling will only be performed if the 6619optimizer believes it is safe to do so. 6620 6621'``llvm.loop.unroll.count``' Metadata 6622^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6623 6624This metadata suggests an unroll factor to the loop unroller. The 6625first operand is the string ``llvm.loop.unroll.count`` and the second 6626operand is a positive integer specifying the unroll factor. For 6627example: 6628 6629.. code-block:: llvm 6630 6631 !0 = !{!"llvm.loop.unroll.count", i32 4} 6632 6633If the trip count of the loop is less than the unroll count the loop 6634will be partially unrolled. 6635 6636'``llvm.loop.unroll.disable``' Metadata 6637^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6638 6639This metadata disables loop unrolling. The metadata has a single operand 6640which is the string ``llvm.loop.unroll.disable``. For example: 6641 6642.. code-block:: llvm 6643 6644 !0 = !{!"llvm.loop.unroll.disable"} 6645 6646'``llvm.loop.unroll.runtime.disable``' Metadata 6647^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6648 6649This metadata disables runtime loop unrolling. The metadata has a single 6650operand which is the string ``llvm.loop.unroll.runtime.disable``. For example: 6651 6652.. code-block:: llvm 6653 6654 !0 = !{!"llvm.loop.unroll.runtime.disable"} 6655 6656'``llvm.loop.unroll.enable``' Metadata 6657^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6658 6659This metadata suggests that the loop should be fully unrolled if the trip count 6660is known at compile time and partially unrolled if the trip count is not known 6661at compile time. The metadata has a single operand which is the string 6662``llvm.loop.unroll.enable``. For example: 6663 6664.. code-block:: llvm 6665 6666 !0 = !{!"llvm.loop.unroll.enable"} 6667 6668'``llvm.loop.unroll.full``' Metadata 6669^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6670 6671This metadata suggests that the loop should be unrolled fully. The 6672metadata has a single operand which is the string ``llvm.loop.unroll.full``. 6673For example: 6674 6675.. code-block:: llvm 6676 6677 !0 = !{!"llvm.loop.unroll.full"} 6678 6679'``llvm.loop.unroll.followup``' Metadata 6680^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6681 6682This metadata defines which loop attributes the unrolled loop will have. 6683See :ref:`Transformation Metadata <transformation-metadata>` for details. 6684 6685'``llvm.loop.unroll.followup_remainder``' Metadata 6686^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6687 6688This metadata defines which loop attributes the remainder loop after 6689partial/runtime unrolling will have. See 6690:ref:`Transformation Metadata <transformation-metadata>` for details. 6691 6692'``llvm.loop.unroll_and_jam``' 6693^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6694 6695This metadata is treated very similarly to the ``llvm.loop.unroll`` metadata 6696above, but affect the unroll and jam pass. In addition any loop with 6697``llvm.loop.unroll`` metadata but no ``llvm.loop.unroll_and_jam`` metadata will 6698disable unroll and jam (so ``llvm.loop.unroll`` metadata will be left to the 6699unroller, plus ``llvm.loop.unroll.disable`` metadata will disable unroll and jam 6700too.) 6701 6702The metadata for unroll and jam otherwise is the same as for ``unroll``. 6703``llvm.loop.unroll_and_jam.enable``, ``llvm.loop.unroll_and_jam.disable`` and 6704``llvm.loop.unroll_and_jam.count`` do the same as for unroll. 6705``llvm.loop.unroll_and_jam.full`` is not supported. Again these are only hints 6706and the normal safety checks will still be performed. 6707 6708'``llvm.loop.unroll_and_jam.count``' Metadata 6709^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6710 6711This metadata suggests an unroll and jam factor to use, similarly to 6712``llvm.loop.unroll.count``. The first operand is the string 6713``llvm.loop.unroll_and_jam.count`` and the second operand is a positive integer 6714specifying the unroll factor. For example: 6715 6716.. code-block:: llvm 6717 6718 !0 = !{!"llvm.loop.unroll_and_jam.count", i32 4} 6719 6720If the trip count of the loop is less than the unroll count the loop 6721will be partially unroll and jammed. 6722 6723'``llvm.loop.unroll_and_jam.disable``' Metadata 6724^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6725 6726This metadata disables loop unroll and jamming. The metadata has a single 6727operand which is the string ``llvm.loop.unroll_and_jam.disable``. For example: 6728 6729.. code-block:: llvm 6730 6731 !0 = !{!"llvm.loop.unroll_and_jam.disable"} 6732 6733'``llvm.loop.unroll_and_jam.enable``' Metadata 6734^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6735 6736This metadata suggests that the loop should be fully unroll and jammed if the 6737trip count is known at compile time and partially unrolled if the trip count is 6738not known at compile time. The metadata has a single operand which is the 6739string ``llvm.loop.unroll_and_jam.enable``. For example: 6740 6741.. code-block:: llvm 6742 6743 !0 = !{!"llvm.loop.unroll_and_jam.enable"} 6744 6745'``llvm.loop.unroll_and_jam.followup_outer``' Metadata 6746^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6747 6748This metadata defines which loop attributes the outer unrolled loop will 6749have. See :ref:`Transformation Metadata <transformation-metadata>` for 6750details. 6751 6752'``llvm.loop.unroll_and_jam.followup_inner``' Metadata 6753^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6754 6755This metadata defines which loop attributes the inner jammed loop will 6756have. See :ref:`Transformation Metadata <transformation-metadata>` for 6757details. 6758 6759'``llvm.loop.unroll_and_jam.followup_remainder_outer``' Metadata 6760^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6761 6762This metadata defines which attributes the epilogue of the outer loop 6763will have. This loop is usually unrolled, meaning there is no such 6764loop. This attribute will be ignored in this case. See 6765:ref:`Transformation Metadata <transformation-metadata>` for details. 6766 6767'``llvm.loop.unroll_and_jam.followup_remainder_inner``' Metadata 6768^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6769 6770This metadata defines which attributes the inner loop of the epilogue 6771will have. The outer epilogue will usually be unrolled, meaning there 6772can be multiple inner remainder loops. See 6773:ref:`Transformation Metadata <transformation-metadata>` for details. 6774 6775'``llvm.loop.unroll_and_jam.followup_all``' Metadata 6776^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6777 6778Attributes specified in the metadata is added to all 6779``llvm.loop.unroll_and_jam.*`` loops. See 6780:ref:`Transformation Metadata <transformation-metadata>` for details. 6781 6782'``llvm.loop.licm_versioning.disable``' Metadata 6783^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6784 6785This metadata indicates that the loop should not be versioned for the purpose 6786of enabling loop-invariant code motion (LICM). The metadata has a single operand 6787which is the string ``llvm.loop.licm_versioning.disable``. For example: 6788 6789.. code-block:: llvm 6790 6791 !0 = !{!"llvm.loop.licm_versioning.disable"} 6792 6793'``llvm.loop.distribute.enable``' Metadata 6794^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6795 6796Loop distribution allows splitting a loop into multiple loops. Currently, 6797this is only performed if the entire loop cannot be vectorized due to unsafe 6798memory dependencies. The transformation will attempt to isolate the unsafe 6799dependencies into their own loop. 6800 6801This metadata can be used to selectively enable or disable distribution of the 6802loop. The first operand is the string ``llvm.loop.distribute.enable`` and the 6803second operand is a bit. If the bit operand value is 1 distribution is 6804enabled. A value of 0 disables distribution: 6805 6806.. code-block:: llvm 6807 6808 !0 = !{!"llvm.loop.distribute.enable", i1 0} 6809 !1 = !{!"llvm.loop.distribute.enable", i1 1} 6810 6811This metadata should be used in conjunction with ``llvm.loop`` loop 6812identification metadata. 6813 6814'``llvm.loop.distribute.followup_coincident``' Metadata 6815^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6816 6817This metadata defines which attributes extracted loops with no cyclic 6818dependencies will have (i.e. can be vectorized). See 6819:ref:`Transformation Metadata <transformation-metadata>` for details. 6820 6821'``llvm.loop.distribute.followup_sequential``' Metadata 6822^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6823 6824This metadata defines which attributes the isolated loops with unsafe 6825memory dependencies will have. See 6826:ref:`Transformation Metadata <transformation-metadata>` for details. 6827 6828'``llvm.loop.distribute.followup_fallback``' Metadata 6829^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6830 6831If loop versioning is necessary, this metadata defined the attributes 6832the non-distributed fallback version will have. See 6833:ref:`Transformation Metadata <transformation-metadata>` for details. 6834 6835'``llvm.loop.distribute.followup_all``' Metadata 6836^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6837 6838The attributes in this metadata is added to all followup loops of the 6839loop distribution pass. See 6840:ref:`Transformation Metadata <transformation-metadata>` for details. 6841 6842'``llvm.licm.disable``' Metadata 6843^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6844 6845This metadata indicates that loop-invariant code motion (LICM) should not be 6846performed on this loop. The metadata has a single operand which is the string 6847``llvm.licm.disable``. For example: 6848 6849.. code-block:: llvm 6850 6851 !0 = !{!"llvm.licm.disable"} 6852 6853Note that although it operates per loop it isn't given the llvm.loop prefix 6854as it is not affected by the ``llvm.loop.disable_nonforced`` metadata. 6855 6856'``llvm.access.group``' Metadata 6857^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6858 6859``llvm.access.group`` metadata can be attached to any instruction that 6860potentially accesses memory. It can point to a single distinct metadata 6861node, which we call access group. This node represents all memory access 6862instructions referring to it via ``llvm.access.group``. When an 6863instruction belongs to multiple access groups, it can also point to a 6864list of accesses groups, illustrated by the following example. 6865 6866.. code-block:: llvm 6867 6868 %val = load i32, ptr %arrayidx, !llvm.access.group !0 6869 ... 6870 !0 = !{!1, !2} 6871 !1 = distinct !{} 6872 !2 = distinct !{} 6873 6874It is illegal for the list node to be empty since it might be confused 6875with an access group. 6876 6877The access group metadata node must be 'distinct' to avoid collapsing 6878multiple access groups by content. A access group metadata node must 6879always be empty which can be used to distinguish an access group 6880metadata node from a list of access groups. Being empty avoids the 6881situation that the content must be updated which, because metadata is 6882immutable by design, would required finding and updating all references 6883to the access group node. 6884 6885The access group can be used to refer to a memory access instruction 6886without pointing to it directly (which is not possible in global 6887metadata). Currently, the only metadata making use of it is 6888``llvm.loop.parallel_accesses``. 6889 6890'``llvm.loop.parallel_accesses``' Metadata 6891^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6892 6893The ``llvm.loop.parallel_accesses`` metadata refers to one or more 6894access group metadata nodes (see ``llvm.access.group``). It denotes that 6895no loop-carried memory dependence exist between it and other instructions 6896in the loop with this metadata. 6897 6898Let ``m1`` and ``m2`` be two instructions that both have the 6899``llvm.access.group`` metadata to the access group ``g1``, respectively 6900``g2`` (which might be identical). If a loop contains both access groups 6901in its ``llvm.loop.parallel_accesses`` metadata, then the compiler can 6902assume that there is no dependency between ``m1`` and ``m2`` carried by 6903this loop. Instructions that belong to multiple access groups are 6904considered having this property if at least one of the access groups 6905matches the ``llvm.loop.parallel_accesses`` list. 6906 6907If all memory-accessing instructions in a loop have 6908``llvm.access.group`` metadata that each refer to one of the access 6909groups of a loop's ``llvm.loop.parallel_accesses`` metadata, then the 6910loop has no loop carried memory dependences and is considered to be a 6911parallel loop. 6912 6913Note that if not all memory access instructions belong to an access 6914group referred to by ``llvm.loop.parallel_accesses``, then the loop must 6915not be considered trivially parallel. Additional 6916memory dependence analysis is required to make that determination. As a fail 6917safe mechanism, this causes loops that were originally parallel to be considered 6918sequential (if optimization passes that are unaware of the parallel semantics 6919insert new memory instructions into the loop body). 6920 6921Example of a loop that is considered parallel due to its correct use of 6922both ``llvm.access.group`` and ``llvm.loop.parallel_accesses`` 6923metadata types. 6924 6925.. code-block:: llvm 6926 6927 for.body: 6928 ... 6929 %val0 = load i32, ptr %arrayidx, !llvm.access.group !1 6930 ... 6931 store i32 %val0, ptr %arrayidx1, !llvm.access.group !1 6932 ... 6933 br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0 6934 6935 for.end: 6936 ... 6937 !0 = distinct !{!0, !{!"llvm.loop.parallel_accesses", !1}} 6938 !1 = distinct !{} 6939 6940It is also possible to have nested parallel loops: 6941 6942.. code-block:: llvm 6943 6944 outer.for.body: 6945 ... 6946 %val1 = load i32, ptr %arrayidx3, !llvm.access.group !4 6947 ... 6948 br label %inner.for.body 6949 6950 inner.for.body: 6951 ... 6952 %val0 = load i32, ptr %arrayidx1, !llvm.access.group !3 6953 ... 6954 store i32 %val0, ptr %arrayidx2, !llvm.access.group !3 6955 ... 6956 br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1 6957 6958 inner.for.end: 6959 ... 6960 store i32 %val1, ptr %arrayidx4, !llvm.access.group !4 6961 ... 6962 br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2 6963 6964 outer.for.end: ; preds = %for.body 6965 ... 6966 !1 = distinct !{!1, !{!"llvm.loop.parallel_accesses", !3}} ; metadata for the inner loop 6967 !2 = distinct !{!2, !{!"llvm.loop.parallel_accesses", !3, !4}} ; metadata for the outer loop 6968 !3 = distinct !{} ; access group for instructions in the inner loop (which are implicitly contained in outer loop as well) 6969 !4 = distinct !{} ; access group for instructions in the outer, but not the inner loop 6970 6971.. _langref_llvm_loop_mustprogress: 6972 6973'``llvm.loop.mustprogress``' Metadata 6974^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6975 6976The ``llvm.loop.mustprogress`` metadata indicates that this loop is required to 6977terminate, unwind, or interact with the environment in an observable way e.g. 6978via a volatile memory access, I/O, or other synchronization. If such a loop is 6979not found to interact with the environment in an observable way, the loop may 6980be removed. This corresponds to the ``mustprogress`` function attribute. 6981 6982'``irr_loop``' Metadata 6983^^^^^^^^^^^^^^^^^^^^^^^ 6984 6985``irr_loop`` metadata may be attached to the terminator instruction of a basic 6986block that's an irreducible loop header (note that an irreducible loop has more 6987than once header basic blocks.) If ``irr_loop`` metadata is attached to the 6988terminator instruction of a basic block that is not really an irreducible loop 6989header, the behavior is undefined. The intent of this metadata is to improve the 6990accuracy of the block frequency propagation. For example, in the code below, the 6991block ``header0`` may have a loop header weight (relative to the other headers of 6992the irreducible loop) of 100: 6993 6994.. code-block:: llvm 6995 6996 header0: 6997 ... 6998 br i1 %cmp, label %t1, label %t2, !irr_loop !0 6999 7000 ... 7001 !0 = !{"loop_header_weight", i64 100} 7002 7003Irreducible loop header weights are typically based on profile data. 7004 7005.. _md_invariant.group: 7006 7007'``invariant.group``' Metadata 7008^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 7009 7010The experimental ``invariant.group`` metadata may be attached to 7011``load``/``store`` instructions referencing a single metadata with no entries. 7012The existence of the ``invariant.group`` metadata on the instruction tells 7013the optimizer that every ``load`` and ``store`` to the same pointer operand 7014can be assumed to load or store the same 7015value (but see the ``llvm.launder.invariant.group`` intrinsic which affects 7016when two pointers are considered the same). Pointers returned by bitcast or 7017getelementptr with only zero indices are considered the same. 7018 7019Examples: 7020 7021.. code-block:: llvm 7022 7023 @unknownPtr = external global i8 7024 ... 7025 %ptr = alloca i8 7026 store i8 42, ptr %ptr, !invariant.group !0 7027 call void @foo(ptr %ptr) 7028 7029 %a = load i8, ptr %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change 7030 call void @foo(ptr %ptr) 7031 7032 %newPtr = call ptr @getPointer(ptr %ptr) 7033 %c = load i8, ptr %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr 7034 7035 %unknownValue = load i8, ptr @unknownPtr 7036 store i8 %unknownValue, ptr %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42 7037 7038 call void @foo(ptr %ptr) 7039 %newPtr2 = call ptr @llvm.launder.invariant.group.p0(ptr %ptr) 7040 %d = load i8, ptr %newPtr2, !invariant.group !0 ; Can't step through launder.invariant.group to get value of %ptr 7041 7042 ... 7043 declare void @foo(ptr) 7044 declare ptr @getPointer(ptr) 7045 declare ptr @llvm.launder.invariant.group.p0(ptr) 7046 7047 !0 = !{} 7048 7049The invariant.group metadata must be dropped when replacing one pointer by 7050another based on aliasing information. This is because invariant.group is tied 7051to the SSA value of the pointer operand. 7052 7053.. code-block:: llvm 7054 7055 %v = load i8, ptr %x, !invariant.group !0 7056 ; if %x mustalias %y then we can replace the above instruction with 7057 %v = load i8, ptr %y 7058 7059Note that this is an experimental feature, which means that its semantics might 7060change in the future. 7061 7062'``type``' Metadata 7063^^^^^^^^^^^^^^^^^^^ 7064 7065See :doc:`TypeMetadata`. 7066 7067'``associated``' Metadata 7068^^^^^^^^^^^^^^^^^^^^^^^^^ 7069 7070The ``associated`` metadata may be attached to a global variable definition with 7071a single argument that references a global object (optionally through an alias). 7072 7073This metadata lowers to the ELF section flag ``SHF_LINK_ORDER`` which prevents 7074discarding of the global variable in linker GC unless the referenced object is 7075also discarded. The linker support for this feature is spotty. For best 7076compatibility, globals carrying this metadata should: 7077 7078- Be in ``@llvm.compiler.used``. 7079- If the referenced global variable is in a comdat, be in the same comdat. 7080 7081``!associated`` can not express many-to-one relationship. A global variable with 7082the metadata should generally not be referenced by a function: the function may 7083be inlined into other functions, leading to more references to the metadata. 7084Ideally we would want to keep metadata alive as long as any inline location is 7085alive, but this many-to-one relationship is not representable. Moreover, if the 7086metadata is retained while the function is discarded, the linker will report an 7087error of a relocation referencing a discarded section. 7088 7089The metadata is often used with an explicit section consisting of valid C 7090identifiers so that the runtime can find the metadata section with 7091linker-defined encapsulation symbols ``__start_<section_name>`` and 7092``__stop_<section_name>``. 7093 7094It does not have any effect on non-ELF targets. 7095 7096Example: 7097 7098.. code-block:: text 7099 7100 $a = comdat any 7101 @a = global i32 1, comdat $a 7102 @b = internal global i32 2, comdat $a, section "abc", !associated !0 7103 !0 = !{ptr @a} 7104 7105 7106'``prof``' Metadata 7107^^^^^^^^^^^^^^^^^^^ 7108 7109The ``prof`` metadata is used to record profile data in the IR. 7110The first operand of the metadata node indicates the profile metadata 7111type. There are currently 3 types: 7112:ref:`branch_weights<prof_node_branch_weights>`, 7113:ref:`function_entry_count<prof_node_function_entry_count>`, and 7114:ref:`VP<prof_node_VP>`. 7115 7116.. _prof_node_branch_weights: 7117 7118branch_weights 7119"""""""""""""" 7120 7121Branch weight metadata attached to a branch, select, switch or call instruction 7122represents the likeliness of the associated branch being taken. 7123For more information, see :doc:`BranchWeightMetadata`. 7124 7125.. _prof_node_function_entry_count: 7126 7127function_entry_count 7128"""""""""""""""""""" 7129 7130Function entry count metadata can be attached to function definitions 7131to record the number of times the function is called. Used with BFI 7132information, it is also used to derive the basic block profile count. 7133For more information, see :doc:`BranchWeightMetadata`. 7134 7135.. _prof_node_VP: 7136 7137VP 7138"" 7139 7140VP (value profile) metadata can be attached to instructions that have 7141value profile information. Currently this is indirect calls (where it 7142records the hottest callees) and calls to memory intrinsics such as memcpy, 7143memmove, and memset (where it records the hottest byte lengths). 7144 7145Each VP metadata node contains "VP" string, then a uint32_t value for the value 7146profiling kind, a uint64_t value for the total number of times the instruction 7147is executed, followed by uint64_t value and execution count pairs. 7148The value profiling kind is 0 for indirect call targets and 1 for memory 7149operations. For indirect call targets, each profile value is a hash 7150of the callee function name, and for memory operations each value is the 7151byte length. 7152 7153Note that the value counts do not need to add up to the total count 7154listed in the third operand (in practice only the top hottest values 7155are tracked and reported). 7156 7157Indirect call example: 7158 7159.. code-block:: llvm 7160 7161 call void %f(), !prof !1 7162 !1 = !{!"VP", i32 0, i64 1600, i64 7651369219802541373, i64 1030, i64 -4377547752858689819, i64 410} 7163 7164Note that the VP type is 0 (the second operand), which indicates this is 7165an indirect call value profile data. The third operand indicates that the 7166indirect call executed 1600 times. The 4th and 6th operands give the 7167hashes of the 2 hottest target functions' names (this is the same hash used 7168to represent function names in the profile database), and the 5th and 7th 7169operands give the execution count that each of the respective prior target 7170functions was called. 7171 7172.. _md_annotation: 7173 7174'``annotation``' Metadata 7175^^^^^^^^^^^^^^^^^^^^^^^^^ 7176 7177The ``annotation`` metadata can be used to attach a tuple of annotation strings 7178to any instruction. This metadata does not impact the semantics of the program 7179and may only be used to provide additional insight about the program and 7180transformations to users. 7181 7182Example: 7183 7184.. code-block:: text 7185 7186 %a.addr = alloca ptr, align 8, !annotation !0 7187 !0 = !{!"auto-init"} 7188 7189'``func_sanitize``' Metadata 7190^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 7191 7192The ``func_sanitize`` metadata is used to attach two values for the function 7193sanitizer instrumentation. The first value is the ubsan function signature. 7194The second value is the address of the proxy variable which stores the address 7195of the RTTI descriptor. If :ref:`prologue <prologuedata>` and '``func_sanitize``' 7196are used at the same time, :ref:`prologue <prologuedata>` is emitted before 7197'``func_sanitize``' in the output. 7198 7199Example: 7200 7201.. code-block:: text 7202 7203 @__llvm_rtti_proxy = private unnamed_addr constant ptr @_ZTIFvvE 7204 define void @_Z3funv() !func_sanitize !0 { 7205 return void 7206 } 7207 !0 = !{i32 846595819, ptr @__llvm_rtti_proxy} 7208 7209Module Flags Metadata 7210===================== 7211 7212Information about the module as a whole is difficult to convey to LLVM's 7213subsystems. The LLVM IR isn't sufficient to transmit this information. 7214The ``llvm.module.flags`` named metadata exists in order to facilitate 7215this. These flags are in the form of key / value pairs --- much like a 7216dictionary --- making it easy for any subsystem who cares about a flag to 7217look it up. 7218 7219The ``llvm.module.flags`` metadata contains a list of metadata triplets. 7220Each triplet has the following form: 7221 7222- The first element is a *behavior* flag, which specifies the behavior 7223 when two (or more) modules are merged together, and it encounters two 7224 (or more) metadata with the same ID. The supported behaviors are 7225 described below. 7226- The second element is a metadata string that is a unique ID for the 7227 metadata. Each module may only have one flag entry for each unique ID (not 7228 including entries with the **Require** behavior). 7229- The third element is the value of the flag. 7230 7231When two (or more) modules are merged together, the resulting 7232``llvm.module.flags`` metadata is the union of the modules' flags. That is, for 7233each unique metadata ID string, there will be exactly one entry in the merged 7234modules ``llvm.module.flags`` metadata table, and the value for that entry will 7235be determined by the merge behavior flag, as described below. The only exception 7236is that entries with the *Require* behavior are always preserved. 7237 7238The following behaviors are supported: 7239 7240.. list-table:: 7241 :header-rows: 1 7242 :widths: 10 90 7243 7244 * - Value 7245 - Behavior 7246 7247 * - 1 7248 - **Error** 7249 Emits an error if two values disagree, otherwise the resulting value 7250 is that of the operands. 7251 7252 * - 2 7253 - **Warning** 7254 Emits a warning if two values disagree. The result value will be the 7255 operand for the flag from the first module being linked, or the max 7256 if the other module uses **Max** (in which case the resulting flag 7257 will be **Max**). 7258 7259 * - 3 7260 - **Require** 7261 Adds a requirement that another module flag be present and have a 7262 specified value after linking is performed. The value must be a 7263 metadata pair, where the first element of the pair is the ID of the 7264 module flag to be restricted, and the second element of the pair is 7265 the value the module flag should be restricted to. This behavior can 7266 be used to restrict the allowable results (via triggering of an 7267 error) of linking IDs with the **Override** behavior. 7268 7269 * - 4 7270 - **Override** 7271 Uses the specified value, regardless of the behavior or value of the 7272 other module. If both modules specify **Override**, but the values 7273 differ, an error will be emitted. 7274 7275 * - 5 7276 - **Append** 7277 Appends the two values, which are required to be metadata nodes. 7278 7279 * - 6 7280 - **AppendUnique** 7281 Appends the two values, which are required to be metadata 7282 nodes. However, duplicate entries in the second list are dropped 7283 during the append operation. 7284 7285 * - 7 7286 - **Max** 7287 Takes the max of the two values, which are required to be integers. 7288 7289 * - 8 7290 - **Min** 7291 Takes the min of the two values, which are required to be non-negative integers. 7292 An absent module flag is treated as having the value 0. 7293 7294It is an error for a particular unique flag ID to have multiple behaviors, 7295except in the case of **Require** (which adds restrictions on another metadata 7296value) or **Override**. 7297 7298An example of module flags: 7299 7300.. code-block:: llvm 7301 7302 !0 = !{ i32 1, !"foo", i32 1 } 7303 !1 = !{ i32 4, !"bar", i32 37 } 7304 !2 = !{ i32 2, !"qux", i32 42 } 7305 !3 = !{ i32 3, !"qux", 7306 !{ 7307 !"foo", i32 1 7308 } 7309 } 7310 !llvm.module.flags = !{ !0, !1, !2, !3 } 7311 7312- Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior 7313 if two or more ``!"foo"`` flags are seen is to emit an error if their 7314 values are not equal. 7315 7316- Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The 7317 behavior if two or more ``!"bar"`` flags are seen is to use the value 7318 '37'. 7319 7320- Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The 7321 behavior if two or more ``!"qux"`` flags are seen is to emit a 7322 warning if their values are not equal. 7323 7324- Metadata ``!3`` has the ID ``!"qux"`` and the value: 7325 7326 :: 7327 7328 !{ !"foo", i32 1 } 7329 7330 The behavior is to emit an error if the ``llvm.module.flags`` does not 7331 contain a flag with the ID ``!"foo"`` that has the value '1' after linking is 7332 performed. 7333 7334Synthesized Functions Module Flags Metadata 7335------------------------------------------- 7336 7337These metadata specify the default attributes synthesized functions should have. 7338These metadata are currently respected by a few instrumentation passes, such as 7339sanitizers. 7340 7341These metadata correspond to a few function attributes with significant code 7342generation behaviors. Function attributes with just optimization purposes 7343should not be listed because the performance impact of these synthesized 7344functions is small. 7345 7346- "frame-pointer": **Max**. The value can be 0, 1, or 2. A synthesized function 7347 will get the "frame-pointer" function attribute, with value being "none", 7348 "non-leaf", or "all", respectively. 7349- "function_return_thunk_extern": The synthesized function will get the 7350 ``fn_return_thunk_extern`` function attribute. 7351- "uwtable": **Max**. The value can be 0, 1, or 2. If the value is 1, a synthesized 7352 function will get the ``uwtable(sync)`` function attribute, if the value is 2, 7353 a synthesized function will get the ``uwtable(async)`` function attribute. 7354 7355Objective-C Garbage Collection Module Flags Metadata 7356---------------------------------------------------- 7357 7358On the Mach-O platform, Objective-C stores metadata about garbage 7359collection in a special section called "image info". The metadata 7360consists of a version number and a bitmask specifying what types of 7361garbage collection are supported (if any) by the file. If two or more 7362modules are linked together their garbage collection metadata needs to 7363be merged rather than appended together. 7364 7365The Objective-C garbage collection module flags metadata consists of the 7366following key-value pairs: 7367 7368.. list-table:: 7369 :header-rows: 1 7370 :widths: 30 70 7371 7372 * - Key 7373 - Value 7374 7375 * - ``Objective-C Version`` 7376 - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2. 7377 7378 * - ``Objective-C Image Info Version`` 7379 - **[Required]** --- The version of the image info section. Currently 7380 always 0. 7381 7382 * - ``Objective-C Image Info Section`` 7383 - **[Required]** --- The section to place the metadata. Valid values are 7384 ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and 7385 ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for 7386 Objective-C ABI version 2. 7387 7388 * - ``Objective-C Garbage Collection`` 7389 - **[Required]** --- Specifies whether garbage collection is supported or 7390 not. Valid values are 0, for no garbage collection, and 2, for garbage 7391 collection supported. 7392 7393 * - ``Objective-C GC Only`` 7394 - **[Optional]** --- Specifies that only garbage collection is supported. 7395 If present, its value must be 6. This flag requires that the 7396 ``Objective-C Garbage Collection`` flag have the value 2. 7397 7398Some important flag interactions: 7399 7400- If a module with ``Objective-C Garbage Collection`` set to 0 is 7401 merged with a module with ``Objective-C Garbage Collection`` set to 7402 2, then the resulting module has the 7403 ``Objective-C Garbage Collection`` flag set to 0. 7404- A module with ``Objective-C Garbage Collection`` set to 0 cannot be 7405 merged with a module with ``Objective-C GC Only`` set to 6. 7406 7407C type width Module Flags Metadata 7408---------------------------------- 7409 7410The ARM backend emits a section into each generated object file describing the 7411options that it was compiled with (in a compiler-independent way) to prevent 7412linking incompatible objects, and to allow automatic library selection. Some 7413of these options are not visible at the IR level, namely wchar_t width and enum 7414width. 7415 7416To pass this information to the backend, these options are encoded in module 7417flags metadata, using the following key-value pairs: 7418 7419.. list-table:: 7420 :header-rows: 1 7421 :widths: 30 70 7422 7423 * - Key 7424 - Value 7425 7426 * - short_wchar 7427 - * 0 --- sizeof(wchar_t) == 4 7428 * 1 --- sizeof(wchar_t) == 2 7429 7430 * - short_enum 7431 - * 0 --- Enums are at least as large as an ``int``. 7432 * 1 --- Enums are stored in the smallest integer type which can 7433 represent all of its values. 7434 7435For example, the following metadata section specifies that the module was 7436compiled with a ``wchar_t`` width of 4 bytes, and the underlying type of an 7437enum is the smallest type which can represent all of its values:: 7438 7439 !llvm.module.flags = !{!0, !1} 7440 !0 = !{i32 1, !"short_wchar", i32 1} 7441 !1 = !{i32 1, !"short_enum", i32 0} 7442 7443LTO Post-Link Module Flags Metadata 7444----------------------------------- 7445 7446Some optimisations are only when the entire LTO unit is present in the current 7447module. This is represented by the ``LTOPostLink`` module flags metadata, which 7448will be created with a value of ``1`` when LTO linking occurs. 7449 7450Embedded Objects Names Metadata 7451=============================== 7452 7453Offloading compilations need to embed device code into the host section table to 7454create a fat binary. This metadata node references each global that will be 7455embedded in the module. The primary use for this is to make referencing these 7456globals more efficient in the IR. The metadata references nodes containing 7457pointers to the global to be embedded followed by the section name it will be 7458stored at:: 7459 7460 !llvm.embedded.objects = !{!0} 7461 !0 = !{ptr @object, !".section"} 7462 7463Automatic Linker Flags Named Metadata 7464===================================== 7465 7466Some targets support embedding of flags to the linker inside individual object 7467files. Typically this is used in conjunction with language extensions which 7468allow source files to contain linker command line options, and have these 7469automatically be transmitted to the linker via object files. 7470 7471These flags are encoded in the IR using named metadata with the name 7472``!llvm.linker.options``. Each operand is expected to be a metadata node 7473which should be a list of other metadata nodes, each of which should be a 7474list of metadata strings defining linker options. 7475 7476For example, the following metadata section specifies two separate sets of 7477linker options, presumably to link against ``libz`` and the ``Cocoa`` 7478framework:: 7479 7480 !0 = !{ !"-lz" } 7481 !1 = !{ !"-framework", !"Cocoa" } 7482 !llvm.linker.options = !{ !0, !1 } 7483 7484The metadata encoding as lists of lists of options, as opposed to a collapsed 7485list of options, is chosen so that the IR encoding can use multiple option 7486strings to specify e.g., a single library, while still having that specifier be 7487preserved as an atomic element that can be recognized by a target specific 7488assembly writer or object file emitter. 7489 7490Each individual option is required to be either a valid option for the target's 7491linker, or an option that is reserved by the target specific assembly writer or 7492object file emitter. No other aspect of these options is defined by the IR. 7493 7494Dependent Libs Named Metadata 7495============================= 7496 7497Some targets support embedding of strings into object files to indicate 7498a set of libraries to add to the link. Typically this is used in conjunction 7499with language extensions which allow source files to explicitly declare the 7500libraries they depend on, and have these automatically be transmitted to the 7501linker via object files. 7502 7503The list is encoded in the IR using named metadata with the name 7504``!llvm.dependent-libraries``. Each operand is expected to be a metadata node 7505which should contain a single string operand. 7506 7507For example, the following metadata section contains two library specifiers:: 7508 7509 !0 = !{!"a library specifier"} 7510 !1 = !{!"another library specifier"} 7511 !llvm.dependent-libraries = !{ !0, !1 } 7512 7513Each library specifier will be handled independently by the consuming linker. 7514The effect of the library specifiers are defined by the consuming linker. 7515 7516.. _summary: 7517 7518ThinLTO Summary 7519=============== 7520 7521Compiling with `ThinLTO <https://clang.llvm.org/docs/ThinLTO.html>`_ 7522causes the building of a compact summary of the module that is emitted into 7523the bitcode. The summary is emitted into the LLVM assembly and identified 7524in syntax by a caret ('``^``'). 7525 7526The summary is parsed into a bitcode output, along with the Module 7527IR, via the "``llvm-as``" tool. Tools that parse the Module IR for the purposes 7528of optimization (e.g. "``clang -x ir``" and "``opt``"), will ignore the 7529summary entries (just as they currently ignore summary entries in a bitcode 7530input file). 7531 7532Eventually, the summary will be parsed into a ModuleSummaryIndex object under 7533the same conditions where summary index is currently built from bitcode. 7534Specifically, tools that test the Thin Link portion of a ThinLTO compile 7535(i.e. llvm-lto and llvm-lto2), or when parsing a combined index 7536for a distributed ThinLTO backend via clang's "``-fthinlto-index=<>``" flag 7537(this part is not yet implemented, use llvm-as to create a bitcode object 7538before feeding into thin link tools for now). 7539 7540There are currently 3 types of summary entries in the LLVM assembly: 7541:ref:`module paths<module_path_summary>`, 7542:ref:`global values<gv_summary>`, and 7543:ref:`type identifiers<typeid_summary>`. 7544 7545.. _module_path_summary: 7546 7547Module Path Summary Entry 7548------------------------- 7549 7550Each module path summary entry lists a module containing global values included 7551in the summary. For a single IR module there will be one such entry, but 7552in a combined summary index produced during the thin link, there will be 7553one module path entry per linked module with summary. 7554 7555Example: 7556 7557.. code-block:: text 7558 7559 ^0 = module: (path: "/path/to/file.o", hash: (2468601609, 1329373163, 1565878005, 638838075, 3148790418)) 7560 7561The ``path`` field is a string path to the bitcode file, and the ``hash`` 7562field is the 160-bit SHA-1 hash of the IR bitcode contents, used for 7563incremental builds and caching. 7564 7565.. _gv_summary: 7566 7567Global Value Summary Entry 7568-------------------------- 7569 7570Each global value summary entry corresponds to a global value defined or 7571referenced by a summarized module. 7572 7573Example: 7574 7575.. code-block:: text 7576 7577 ^4 = gv: (name: "f"[, summaries: (Summary)[, (Summary)]*]?) ; guid = 14740650423002898831 7578 7579For declarations, there will not be a summary list. For definitions, a 7580global value will contain a list of summaries, one per module containing 7581a definition. There can be multiple entries in a combined summary index 7582for symbols with weak linkage. 7583 7584Each ``Summary`` format will depend on whether the global value is a 7585:ref:`function<function_summary>`, :ref:`variable<variable_summary>`, or 7586:ref:`alias<alias_summary>`. 7587 7588.. _function_summary: 7589 7590Function Summary 7591^^^^^^^^^^^^^^^^ 7592 7593If the global value is a function, the ``Summary`` entry will look like: 7594 7595.. code-block:: text 7596 7597 function: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), insts: 2[, FuncFlags]?[, Calls]?[, TypeIdInfo]?[, Params]?[, Refs]? 7598 7599The ``module`` field includes the summary entry id for the module containing 7600this definition, and the ``flags`` field contains information such as 7601the linkage type, a flag indicating whether it is legal to import the 7602definition, whether it is globally live and whether the linker resolved it 7603to a local definition (the latter two are populated during the thin link). 7604The ``insts`` field contains the number of IR instructions in the function. 7605Finally, there are several optional fields: :ref:`FuncFlags<funcflags_summary>`, 7606:ref:`Calls<calls_summary>`, :ref:`TypeIdInfo<typeidinfo_summary>`, 7607:ref:`Params<params_summary>`, :ref:`Refs<refs_summary>`. 7608 7609.. _variable_summary: 7610 7611Global Variable Summary 7612^^^^^^^^^^^^^^^^^^^^^^^ 7613 7614If the global value is a variable, the ``Summary`` entry will look like: 7615 7616.. code-block:: text 7617 7618 variable: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0)[, Refs]? 7619 7620The variable entry contains a subset of the fields in a 7621:ref:`function summary <function_summary>`, see the descriptions there. 7622 7623.. _alias_summary: 7624 7625Alias Summary 7626^^^^^^^^^^^^^ 7627 7628If the global value is an alias, the ``Summary`` entry will look like: 7629 7630.. code-block:: text 7631 7632 alias: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), aliasee: ^2) 7633 7634The ``module`` and ``flags`` fields are as described for a 7635:ref:`function summary <function_summary>`. The ``aliasee`` field 7636contains a reference to the global value summary entry of the aliasee. 7637 7638.. _funcflags_summary: 7639 7640Function Flags 7641^^^^^^^^^^^^^^ 7642 7643The optional ``FuncFlags`` field looks like: 7644 7645.. code-block:: text 7646 7647 funcFlags: (readNone: 0, readOnly: 0, noRecurse: 0, returnDoesNotAlias: 0, noInline: 0, alwaysInline: 0, noUnwind: 1, mayThrow: 0, hasUnknownCall: 0) 7648 7649If unspecified, flags are assumed to hold the conservative ``false`` value of 7650``0``. 7651 7652.. _calls_summary: 7653 7654Calls 7655^^^^^ 7656 7657The optional ``Calls`` field looks like: 7658 7659.. code-block:: text 7660 7661 calls: ((Callee)[, (Callee)]*) 7662 7663where each ``Callee`` looks like: 7664 7665.. code-block:: text 7666 7667 callee: ^1[, hotness: None]?[, relbf: 0]? 7668 7669The ``callee`` refers to the summary entry id of the callee. At most one 7670of ``hotness`` (which can take the values ``Unknown``, ``Cold``, ``None``, 7671``Hot``, and ``Critical``), and ``relbf`` (which holds the integer 7672branch frequency relative to the entry frequency, scaled down by 2^8) 7673may be specified. The defaults are ``Unknown`` and ``0``, respectively. 7674 7675.. _params_summary: 7676 7677Params 7678^^^^^^ 7679 7680The optional ``Params`` is used by ``StackSafety`` and looks like: 7681 7682.. code-block:: text 7683 7684 Params: ((Param)[, (Param)]*) 7685 7686where each ``Param`` describes pointer parameter access inside of the 7687function and looks like: 7688 7689.. code-block:: text 7690 7691 param: 4, offset: [0, 5][, calls: ((Callee)[, (Callee)]*)]? 7692 7693where the first ``param`` is the number of the parameter it describes, 7694``offset`` is the inclusive range of offsets from the pointer parameter to bytes 7695which can be accessed by the function. This range does not include accesses by 7696function calls from ``calls`` list. 7697 7698where each ``Callee`` describes how parameter is forwarded into other 7699functions and looks like: 7700 7701.. code-block:: text 7702 7703 callee: ^3, param: 5, offset: [-3, 3] 7704 7705The ``callee`` refers to the summary entry id of the callee, ``param`` is 7706the number of the callee parameter which points into the callers parameter 7707with offset known to be inside of the ``offset`` range. ``calls`` will be 7708consumed and removed by thin link stage to update ``Param::offset`` so it 7709covers all accesses possible by ``calls``. 7710 7711Pointer parameter without corresponding ``Param`` is considered unsafe and we 7712assume that access with any offset is possible. 7713 7714Example: 7715 7716If we have the following function: 7717 7718.. code-block:: text 7719 7720 define i64 @foo(ptr %0, ptr %1, ptr %2, i8 %3) { 7721 store ptr %1, ptr @x 7722 %5 = getelementptr inbounds i8, ptr %2, i64 5 7723 %6 = load i8, ptr %5 7724 %7 = getelementptr inbounds i8, ptr %2, i8 %3 7725 tail call void @bar(i8 %3, ptr %7) 7726 %8 = load i64, ptr %0 7727 ret i64 %8 7728 } 7729 7730We can expect the record like this: 7731 7732.. code-block:: text 7733 7734 params: ((param: 0, offset: [0, 7]),(param: 2, offset: [5, 5], calls: ((callee: ^3, param: 1, offset: [-128, 127])))) 7735 7736The function may access just 8 bytes of the parameter %0 . ``calls`` is empty, 7737so the parameter is either not used for function calls or ``offset`` already 7738covers all accesses from nested function calls. 7739Parameter %1 escapes, so access is unknown. 7740The function itself can access just a single byte of the parameter %2. Additional 7741access is possible inside of the ``@bar`` or ``^3``. The function adds signed 7742offset to the pointer and passes the result as the argument %1 into ``^3``. 7743This record itself does not tell us how ``^3`` will access the parameter. 7744Parameter %3 is not a pointer. 7745 7746.. _refs_summary: 7747 7748Refs 7749^^^^ 7750 7751The optional ``Refs`` field looks like: 7752 7753.. code-block:: text 7754 7755 refs: ((Ref)[, (Ref)]*) 7756 7757where each ``Ref`` contains a reference to the summary id of the referenced 7758value (e.g. ``^1``). 7759 7760.. _typeidinfo_summary: 7761 7762TypeIdInfo 7763^^^^^^^^^^ 7764 7765The optional ``TypeIdInfo`` field, used for 7766`Control Flow Integrity <https://clang.llvm.org/docs/ControlFlowIntegrity.html>`_, 7767looks like: 7768 7769.. code-block:: text 7770 7771 typeIdInfo: [(TypeTests)]?[, (TypeTestAssumeVCalls)]?[, (TypeCheckedLoadVCalls)]?[, (TypeTestAssumeConstVCalls)]?[, (TypeCheckedLoadConstVCalls)]? 7772 7773These optional fields have the following forms: 7774 7775TypeTests 7776""""""""" 7777 7778.. code-block:: text 7779 7780 typeTests: (TypeIdRef[, TypeIdRef]*) 7781 7782Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>` 7783by summary id or ``GUID``. 7784 7785TypeTestAssumeVCalls 7786"""""""""""""""""""" 7787 7788.. code-block:: text 7789 7790 typeTestAssumeVCalls: (VFuncId[, VFuncId]*) 7791 7792Where each VFuncId has the format: 7793 7794.. code-block:: text 7795 7796 vFuncId: (TypeIdRef, offset: 16) 7797 7798Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>` 7799by summary id or ``GUID`` preceded by a ``guid:`` tag. 7800 7801TypeCheckedLoadVCalls 7802""""""""""""""""""""" 7803 7804.. code-block:: text 7805 7806 typeCheckedLoadVCalls: (VFuncId[, VFuncId]*) 7807 7808Where each VFuncId has the format described for ``TypeTestAssumeVCalls``. 7809 7810TypeTestAssumeConstVCalls 7811""""""""""""""""""""""""" 7812 7813.. code-block:: text 7814 7815 typeTestAssumeConstVCalls: (ConstVCall[, ConstVCall]*) 7816 7817Where each ConstVCall has the format: 7818 7819.. code-block:: text 7820 7821 (VFuncId, args: (Arg[, Arg]*)) 7822 7823and where each VFuncId has the format described for ``TypeTestAssumeVCalls``, 7824and each Arg is an integer argument number. 7825 7826TypeCheckedLoadConstVCalls 7827"""""""""""""""""""""""""" 7828 7829.. code-block:: text 7830 7831 typeCheckedLoadConstVCalls: (ConstVCall[, ConstVCall]*) 7832 7833Where each ConstVCall has the format described for 7834``TypeTestAssumeConstVCalls``. 7835 7836.. _typeid_summary: 7837 7838Type ID Summary Entry 7839--------------------- 7840 7841Each type id summary entry corresponds to a type identifier resolution 7842which is generated during the LTO link portion of the compile when building 7843with `Control Flow Integrity <https://clang.llvm.org/docs/ControlFlowIntegrity.html>`_, 7844so these are only present in a combined summary index. 7845 7846Example: 7847 7848.. code-block:: text 7849 7850 ^4 = typeid: (name: "_ZTS1A", summary: (typeTestRes: (kind: allOnes, sizeM1BitWidth: 7[, alignLog2: 0]?[, sizeM1: 0]?[, bitMask: 0]?[, inlineBits: 0]?)[, WpdResolutions]?)) ; guid = 7004155349499253778 7851 7852The ``typeTestRes`` gives the type test resolution ``kind`` (which may 7853be ``unsat``, ``byteArray``, ``inline``, ``single``, or ``allOnes``), and 7854the ``size-1`` bit width. It is followed by optional flags, which default to 0, 7855and an optional WpdResolutions (whole program devirtualization resolution) 7856field that looks like: 7857 7858.. code-block:: text 7859 7860 wpdResolutions: ((offset: 0, WpdRes)[, (offset: 1, WpdRes)]* 7861 7862where each entry is a mapping from the given byte offset to the whole-program 7863devirtualization resolution WpdRes, that has one of the following formats: 7864 7865.. code-block:: text 7866 7867 wpdRes: (kind: branchFunnel) 7868 wpdRes: (kind: singleImpl, singleImplName: "_ZN1A1nEi") 7869 wpdRes: (kind: indir) 7870 7871Additionally, each wpdRes has an optional ``resByArg`` field, which 7872describes the resolutions for calls with all constant integer arguments: 7873 7874.. code-block:: text 7875 7876 resByArg: (ResByArg[, ResByArg]*) 7877 7878where ResByArg is: 7879 7880.. code-block:: text 7881 7882 args: (Arg[, Arg]*), byArg: (kind: UniformRetVal[, info: 0][, byte: 0][, bit: 0]) 7883 7884Where the ``kind`` can be ``Indir``, ``UniformRetVal``, ``UniqueRetVal`` 7885or ``VirtualConstProp``. The ``info`` field is only used if the kind 7886is ``UniformRetVal`` (indicates the uniform return value), or 7887``UniqueRetVal`` (holds the return value associated with the unique vtable 7888(0 or 1)). The ``byte`` and ``bit`` fields are only used if the target does 7889not support the use of absolute symbols to store constants. 7890 7891.. _intrinsicglobalvariables: 7892 7893Intrinsic Global Variables 7894========================== 7895 7896LLVM has a number of "magic" global variables that contain data that 7897affect code generation or other IR semantics. These are documented here. 7898All globals of this sort should have a section specified as 7899"``llvm.metadata``". This section and all globals that start with 7900"``llvm.``" are reserved for use by LLVM. 7901 7902.. _gv_llvmused: 7903 7904The '``llvm.used``' Global Variable 7905----------------------------------- 7906 7907The ``@llvm.used`` global is an array which has 7908:ref:`appending linkage <linkage_appending>`. This array contains a list of 7909pointers to named global variables, functions and aliases which may optionally 7910have a pointer cast formed of bitcast or getelementptr. For example, a legal 7911use of it is: 7912 7913.. code-block:: llvm 7914 7915 @X = global i8 4 7916 @Y = global i32 123 7917 7918 @llvm.used = appending global [2 x ptr] [ 7919 ptr @X, 7920 ptr @Y 7921 ], section "llvm.metadata" 7922 7923If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler, 7924and linker are required to treat the symbol as if there is a reference to the 7925symbol that it cannot see (which is why they have to be named). For example, if 7926a variable has internal linkage and no references other than that from the 7927``@llvm.used`` list, it cannot be deleted. This is commonly used to represent 7928references from inline asms and other things the compiler cannot "see", and 7929corresponds to "``attribute((used))``" in GNU C. 7930 7931On some targets, the code generator must emit a directive to the 7932assembler or object file to prevent the assembler and linker from 7933removing the symbol. 7934 7935.. _gv_llvmcompilerused: 7936 7937The '``llvm.compiler.used``' Global Variable 7938-------------------------------------------- 7939 7940The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used`` 7941directive, except that it only prevents the compiler from touching the 7942symbol. On targets that support it, this allows an intelligent linker to 7943optimize references to the symbol without being impeded as it would be 7944by ``@llvm.used``. 7945 7946This is a rare construct that should only be used in rare circumstances, 7947and should not be exposed to source languages. 7948 7949.. _gv_llvmglobalctors: 7950 7951The '``llvm.global_ctors``' Global Variable 7952------------------------------------------- 7953 7954.. code-block:: llvm 7955 7956 %0 = type { i32, ptr, ptr } 7957 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, ptr @ctor, ptr @data }] 7958 7959The ``@llvm.global_ctors`` array contains a list of constructor 7960functions, priorities, and an associated global or function. 7961The functions referenced by this array will be called in ascending order 7962of priority (i.e. lowest first) when the module is loaded. The order of 7963functions with the same priority is not defined. 7964 7965If the third field is non-null, and points to a global variable 7966or function, the initializer function will only run if the associated 7967data from the current module is not discarded. 7968On ELF the referenced global variable or function must be in a comdat. 7969 7970.. _llvmglobaldtors: 7971 7972The '``llvm.global_dtors``' Global Variable 7973------------------------------------------- 7974 7975.. code-block:: llvm 7976 7977 %0 = type { i32, ptr, ptr } 7978 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, ptr @dtor, ptr @data }] 7979 7980The ``@llvm.global_dtors`` array contains a list of destructor 7981functions, priorities, and an associated global or function. 7982The functions referenced by this array will be called in descending 7983order of priority (i.e. highest first) when the module is unloaded. The 7984order of functions with the same priority is not defined. 7985 7986If the third field is non-null, and points to a global variable 7987or function, the destructor function will only run if the associated 7988data from the current module is not discarded. 7989On ELF the referenced global variable or function must be in a comdat. 7990 7991Instruction Reference 7992===================== 7993 7994The LLVM instruction set consists of several different classifications 7995of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary 7996instructions <binaryops>`, :ref:`bitwise binary 7997instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and 7998:ref:`other instructions <otherops>`. 7999 8000.. _terminators: 8001 8002Terminator Instructions 8003----------------------- 8004 8005As mentioned :ref:`previously <functionstructure>`, every basic block in a 8006program ends with a "Terminator" instruction, which indicates which 8007block should be executed after the current block is finished. These 8008terminator instructions typically yield a '``void``' value: they produce 8009control flow, not values (the one exception being the 8010':ref:`invoke <i_invoke>`' instruction). 8011 8012The terminator instructions are: ':ref:`ret <i_ret>`', 8013':ref:`br <i_br>`', ':ref:`switch <i_switch>`', 8014':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`', 8015':ref:`callbr <i_callbr>`' 8016':ref:`resume <i_resume>`', ':ref:`catchswitch <i_catchswitch>`', 8017':ref:`catchret <i_catchret>`', 8018':ref:`cleanupret <i_cleanupret>`', 8019and ':ref:`unreachable <i_unreachable>`'. 8020 8021.. _i_ret: 8022 8023'``ret``' Instruction 8024^^^^^^^^^^^^^^^^^^^^^ 8025 8026Syntax: 8027""""""" 8028 8029:: 8030 8031 ret <type> <value> ; Return a value from a non-void function 8032 ret void ; Return from void function 8033 8034Overview: 8035""""""""" 8036 8037The '``ret``' instruction is used to return control flow (and optionally 8038a value) from a function back to the caller. 8039 8040There are two forms of the '``ret``' instruction: one that returns a 8041value and then causes control flow, and one that just causes control 8042flow to occur. 8043 8044Arguments: 8045"""""""""" 8046 8047The '``ret``' instruction optionally accepts a single argument, the 8048return value. The type of the return value must be a ':ref:`first 8049class <t_firstclass>`' type. 8050 8051A function is not :ref:`well formed <wellformed>` if it has a non-void 8052return type and contains a '``ret``' instruction with no return value or 8053a return value with a type that does not match its type, or if it has a 8054void return type and contains a '``ret``' instruction with a return 8055value. 8056 8057Semantics: 8058"""""""""" 8059 8060When the '``ret``' instruction is executed, control flow returns back to 8061the calling function's context. If the caller is a 8062":ref:`call <i_call>`" instruction, execution continues at the 8063instruction after the call. If the caller was an 8064":ref:`invoke <i_invoke>`" instruction, execution continues at the 8065beginning of the "normal" destination block. If the instruction returns 8066a value, that value shall set the call or invoke instruction's return 8067value. 8068 8069Example: 8070"""""""" 8071 8072.. code-block:: llvm 8073 8074 ret i32 5 ; Return an integer value of 5 8075 ret void ; Return from a void function 8076 ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2 8077 8078.. _i_br: 8079 8080'``br``' Instruction 8081^^^^^^^^^^^^^^^^^^^^ 8082 8083Syntax: 8084""""""" 8085 8086:: 8087 8088 br i1 <cond>, label <iftrue>, label <iffalse> 8089 br label <dest> ; Unconditional branch 8090 8091Overview: 8092""""""""" 8093 8094The '``br``' instruction is used to cause control flow to transfer to a 8095different basic block in the current function. There are two forms of 8096this instruction, corresponding to a conditional branch and an 8097unconditional branch. 8098 8099Arguments: 8100"""""""""" 8101 8102The conditional branch form of the '``br``' instruction takes a single 8103'``i1``' value and two '``label``' values. The unconditional form of the 8104'``br``' instruction takes a single '``label``' value as a target. 8105 8106Semantics: 8107"""""""""" 8108 8109Upon execution of a conditional '``br``' instruction, the '``i1``' 8110argument is evaluated. If the value is ``true``, control flows to the 8111'``iftrue``' ``label`` argument. If "cond" is ``false``, control flows 8112to the '``iffalse``' ``label`` argument. 8113If '``cond``' is ``poison`` or ``undef``, this instruction has undefined 8114behavior. 8115 8116Example: 8117"""""""" 8118 8119.. code-block:: llvm 8120 8121 Test: 8122 %cond = icmp eq i32 %a, %b 8123 br i1 %cond, label %IfEqual, label %IfUnequal 8124 IfEqual: 8125 ret i32 1 8126 IfUnequal: 8127 ret i32 0 8128 8129.. _i_switch: 8130 8131'``switch``' Instruction 8132^^^^^^^^^^^^^^^^^^^^^^^^ 8133 8134Syntax: 8135""""""" 8136 8137:: 8138 8139 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ] 8140 8141Overview: 8142""""""""" 8143 8144The '``switch``' instruction is used to transfer control flow to one of 8145several different places. It is a generalization of the '``br``' 8146instruction, allowing a branch to occur to one of many possible 8147destinations. 8148 8149Arguments: 8150"""""""""" 8151 8152The '``switch``' instruction uses three parameters: an integer 8153comparison value '``value``', a default '``label``' destination, and an 8154array of pairs of comparison value constants and '``label``'s. The table 8155is not allowed to contain duplicate constant entries. 8156 8157Semantics: 8158"""""""""" 8159 8160The ``switch`` instruction specifies a table of values and destinations. 8161When the '``switch``' instruction is executed, this table is searched 8162for the given value. If the value is found, control flow is transferred 8163to the corresponding destination; otherwise, control flow is transferred 8164to the default destination. 8165If '``value``' is ``poison`` or ``undef``, this instruction has undefined 8166behavior. 8167 8168Implementation: 8169""""""""""""""" 8170 8171Depending on properties of the target machine and the particular 8172``switch`` instruction, this instruction may be code generated in 8173different ways. For example, it could be generated as a series of 8174chained conditional branches or with a lookup table. 8175 8176Example: 8177"""""""" 8178 8179.. code-block:: llvm 8180 8181 ; Emulate a conditional br instruction 8182 %Val = zext i1 %value to i32 8183 switch i32 %Val, label %truedest [ i32 0, label %falsedest ] 8184 8185 ; Emulate an unconditional br instruction 8186 switch i32 0, label %dest [ ] 8187 8188 ; Implement a jump table: 8189 switch i32 %val, label %otherwise [ i32 0, label %onzero 8190 i32 1, label %onone 8191 i32 2, label %ontwo ] 8192 8193.. _i_indirectbr: 8194 8195'``indirectbr``' Instruction 8196^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8197 8198Syntax: 8199""""""" 8200 8201:: 8202 8203 indirectbr ptr <address>, [ label <dest1>, label <dest2>, ... ] 8204 8205Overview: 8206""""""""" 8207 8208The '``indirectbr``' instruction implements an indirect branch to a 8209label within the current function, whose address is specified by 8210"``address``". Address must be derived from a 8211:ref:`blockaddress <blockaddress>` constant. 8212 8213Arguments: 8214"""""""""" 8215 8216The '``address``' argument is the address of the label to jump to. The 8217rest of the arguments indicate the full set of possible destinations 8218that the address may point to. Blocks are allowed to occur multiple 8219times in the destination list, though this isn't particularly useful. 8220 8221This destination list is required so that dataflow analysis has an 8222accurate understanding of the CFG. 8223 8224Semantics: 8225"""""""""" 8226 8227Control transfers to the block specified in the address argument. All 8228possible destination blocks must be listed in the label list, otherwise 8229this instruction has undefined behavior. This implies that jumps to 8230labels defined in other functions have undefined behavior as well. 8231If '``address``' is ``poison`` or ``undef``, this instruction has undefined 8232behavior. 8233 8234Implementation: 8235""""""""""""""" 8236 8237This is typically implemented with a jump through a register. 8238 8239Example: 8240"""""""" 8241 8242.. code-block:: llvm 8243 8244 indirectbr ptr %Addr, [ label %bb1, label %bb2, label %bb3 ] 8245 8246.. _i_invoke: 8247 8248'``invoke``' Instruction 8249^^^^^^^^^^^^^^^^^^^^^^^^ 8250 8251Syntax: 8252""""""" 8253 8254:: 8255 8256 <result> = invoke [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] 8257 [operand bundles] to label <normal label> unwind label <exception label> 8258 8259Overview: 8260""""""""" 8261 8262The '``invoke``' instruction causes control to transfer to a specified 8263function, with the possibility of control flow transfer to either the 8264'``normal``' label or the '``exception``' label. If the callee function 8265returns with the "``ret``" instruction, control flow will return to the 8266"normal" label. If the callee (or any indirect callees) returns via the 8267":ref:`resume <i_resume>`" instruction or other exception handling 8268mechanism, control is interrupted and continued at the dynamically 8269nearest "exception" label. 8270 8271The '``exception``' label is a `landing 8272pad <ExceptionHandling.html#overview>`_ for the exception. As such, 8273'``exception``' label is required to have the 8274":ref:`landingpad <i_landingpad>`" instruction, which contains the 8275information about the behavior of the program after unwinding happens, 8276as its first non-PHI instruction. The restrictions on the 8277"``landingpad``" instruction's tightly couples it to the "``invoke``" 8278instruction, so that the important information contained within the 8279"``landingpad``" instruction can't be lost through normal code motion. 8280 8281Arguments: 8282"""""""""" 8283 8284This instruction requires several arguments: 8285 8286#. The optional "cconv" marker indicates which :ref:`calling 8287 convention <callingconv>` the call should use. If none is 8288 specified, the call defaults to using C calling conventions. 8289#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 8290 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 8291 are valid here. 8292#. The optional addrspace attribute can be used to indicate the address space 8293 of the called function. If it is not specified, the program address space 8294 from the :ref:`datalayout string<langref_datalayout>` will be used. 8295#. '``ty``': the type of the call instruction itself which is also the 8296 type of the return value. Functions that return no value are marked 8297 ``void``. 8298#. '``fnty``': shall be the signature of the function being invoked. The 8299 argument types must match the types implied by this signature. This 8300 type can be omitted if the function is not varargs. 8301#. '``fnptrval``': An LLVM value containing a pointer to a function to 8302 be invoked. In most cases, this is a direct function invocation, but 8303 indirect ``invoke``'s are just as possible, calling an arbitrary pointer 8304 to function value. 8305#. '``function args``': argument list whose types match the function 8306 signature argument types and parameter attributes. All arguments must 8307 be of :ref:`first class <t_firstclass>` type. If the function signature 8308 indicates the function accepts a variable number of arguments, the 8309 extra arguments can be specified. 8310#. '``normal label``': the label reached when the called function 8311 executes a '``ret``' instruction. 8312#. '``exception label``': the label reached when a callee returns via 8313 the :ref:`resume <i_resume>` instruction or other exception handling 8314 mechanism. 8315#. The optional :ref:`function attributes <fnattrs>` list. 8316#. The optional :ref:`operand bundles <opbundles>` list. 8317 8318Semantics: 8319"""""""""" 8320 8321This instruction is designed to operate as a standard '``call``' 8322instruction in most regards. The primary difference is that it 8323establishes an association with a label, which is used by the runtime 8324library to unwind the stack. 8325 8326This instruction is used in languages with destructors to ensure that 8327proper cleanup is performed in the case of either a ``longjmp`` or a 8328thrown exception. Additionally, this is important for implementation of 8329'``catch``' clauses in high-level languages that support them. 8330 8331For the purposes of the SSA form, the definition of the value returned 8332by the '``invoke``' instruction is deemed to occur on the edge from the 8333current block to the "normal" label. If the callee unwinds then no 8334return value is available. 8335 8336Example: 8337"""""""" 8338 8339.. code-block:: llvm 8340 8341 %retval = invoke i32 @Test(i32 15) to label %Continue 8342 unwind label %TestCleanup ; i32:retval set 8343 %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue 8344 unwind label %TestCleanup ; i32:retval set 8345 8346.. _i_callbr: 8347 8348'``callbr``' Instruction 8349^^^^^^^^^^^^^^^^^^^^^^^^ 8350 8351Syntax: 8352""""""" 8353 8354:: 8355 8356 <result> = callbr [cconv] [ret attrs] [addrspace(<num>)] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] 8357 [operand bundles] to label <fallthrough label> [indirect labels] 8358 8359Overview: 8360""""""""" 8361 8362The '``callbr``' instruction causes control to transfer to a specified 8363function, with the possibility of control flow transfer to either the 8364'``fallthrough``' label or one of the '``indirect``' labels. 8365 8366This instruction should only be used to implement the "goto" feature of gcc 8367style inline assembly. Any other usage is an error in the IR verifier. 8368 8369Arguments: 8370"""""""""" 8371 8372This instruction requires several arguments: 8373 8374#. The optional "cconv" marker indicates which :ref:`calling 8375 convention <callingconv>` the call should use. If none is 8376 specified, the call defaults to using C calling conventions. 8377#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 8378 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 8379 are valid here. 8380#. The optional addrspace attribute can be used to indicate the address space 8381 of the called function. If it is not specified, the program address space 8382 from the :ref:`datalayout string<langref_datalayout>` will be used. 8383#. '``ty``': the type of the call instruction itself which is also the 8384 type of the return value. Functions that return no value are marked 8385 ``void``. 8386#. '``fnty``': shall be the signature of the function being called. The 8387 argument types must match the types implied by this signature. This 8388 type can be omitted if the function is not varargs. 8389#. '``fnptrval``': An LLVM value containing a pointer to a function to 8390 be called. In most cases, this is a direct function call, but 8391 other ``callbr``'s are just as possible, calling an arbitrary pointer 8392 to function value. 8393#. '``function args``': argument list whose types match the function 8394 signature argument types and parameter attributes. All arguments must 8395 be of :ref:`first class <t_firstclass>` type. If the function signature 8396 indicates the function accepts a variable number of arguments, the 8397 extra arguments can be specified. 8398#. '``fallthrough label``': the label reached when the inline assembly's 8399 execution exits the bottom. 8400#. '``indirect labels``': the labels reached when a callee transfers control 8401 to a location other than the '``fallthrough label``'. Label constraints 8402 refer to these destinations. 8403#. The optional :ref:`function attributes <fnattrs>` list. 8404#. The optional :ref:`operand bundles <opbundles>` list. 8405 8406Semantics: 8407"""""""""" 8408 8409This instruction is designed to operate as a standard '``call``' 8410instruction in most regards. The primary difference is that it 8411establishes an association with additional labels to define where control 8412flow goes after the call. 8413 8414The output values of a '``callbr``' instruction are available only to 8415the '``fallthrough``' block, not to any '``indirect``' blocks(s). 8416 8417The only use of this today is to implement the "goto" feature of gcc inline 8418assembly where additional labels can be provided as locations for the inline 8419assembly to jump to. 8420 8421Example: 8422"""""""" 8423 8424.. code-block:: llvm 8425 8426 ; "asm goto" without output constraints. 8427 callbr void asm "", "r,!i"(i32 %x) 8428 to label %fallthrough [label %indirect] 8429 8430 ; "asm goto" with output constraints. 8431 <result> = callbr i32 asm "", "=r,r,!i"(i32 %x) 8432 to label %fallthrough [label %indirect] 8433 8434.. _i_resume: 8435 8436'``resume``' Instruction 8437^^^^^^^^^^^^^^^^^^^^^^^^ 8438 8439Syntax: 8440""""""" 8441 8442:: 8443 8444 resume <type> <value> 8445 8446Overview: 8447""""""""" 8448 8449The '``resume``' instruction is a terminator instruction that has no 8450successors. 8451 8452Arguments: 8453"""""""""" 8454 8455The '``resume``' instruction requires one argument, which must have the 8456same type as the result of any '``landingpad``' instruction in the same 8457function. 8458 8459Semantics: 8460"""""""""" 8461 8462The '``resume``' instruction resumes propagation of an existing 8463(in-flight) exception whose unwinding was interrupted with a 8464:ref:`landingpad <i_landingpad>` instruction. 8465 8466Example: 8467"""""""" 8468 8469.. code-block:: llvm 8470 8471 resume { ptr, i32 } %exn 8472 8473.. _i_catchswitch: 8474 8475'``catchswitch``' Instruction 8476^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8477 8478Syntax: 8479""""""" 8480 8481:: 8482 8483 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller 8484 <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default> 8485 8486Overview: 8487""""""""" 8488 8489The '``catchswitch``' instruction is used by `LLVM's exception handling system 8490<ExceptionHandling.html#overview>`_ to describe the set of possible catch handlers 8491that may be executed by the :ref:`EH personality routine <personalityfn>`. 8492 8493Arguments: 8494"""""""""" 8495 8496The ``parent`` argument is the token of the funclet that contains the 8497``catchswitch`` instruction. If the ``catchswitch`` is not inside a funclet, 8498this operand may be the token ``none``. 8499 8500The ``default`` argument is the label of another basic block beginning with 8501either a ``cleanuppad`` or ``catchswitch`` instruction. This unwind destination 8502must be a legal target with respect to the ``parent`` links, as described in 8503the `exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_. 8504 8505The ``handlers`` are a nonempty list of successor blocks that each begin with a 8506:ref:`catchpad <i_catchpad>` instruction. 8507 8508Semantics: 8509"""""""""" 8510 8511Executing this instruction transfers control to one of the successors in 8512``handlers``, if appropriate, or continues to unwind via the unwind label if 8513present. 8514 8515The ``catchswitch`` is both a terminator and a "pad" instruction, meaning that 8516it must be both the first non-phi instruction and last instruction in the basic 8517block. Therefore, it must be the only non-phi instruction in the block. 8518 8519Example: 8520"""""""" 8521 8522.. code-block:: text 8523 8524 dispatch1: 8525 %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to caller 8526 dispatch2: 8527 %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup 8528 8529.. _i_catchret: 8530 8531'``catchret``' Instruction 8532^^^^^^^^^^^^^^^^^^^^^^^^^^ 8533 8534Syntax: 8535""""""" 8536 8537:: 8538 8539 catchret from <token> to label <normal> 8540 8541Overview: 8542""""""""" 8543 8544The '``catchret``' instruction is a terminator instruction that has a 8545single successor. 8546 8547 8548Arguments: 8549"""""""""" 8550 8551The first argument to a '``catchret``' indicates which ``catchpad`` it 8552exits. It must be a :ref:`catchpad <i_catchpad>`. 8553The second argument to a '``catchret``' specifies where control will 8554transfer to next. 8555 8556Semantics: 8557"""""""""" 8558 8559The '``catchret``' instruction ends an existing (in-flight) exception whose 8560unwinding was interrupted with a :ref:`catchpad <i_catchpad>` instruction. The 8561:ref:`personality function <personalityfn>` gets a chance to execute arbitrary 8562code to, for example, destroy the active exception. Control then transfers to 8563``normal``. 8564 8565The ``token`` argument must be a token produced by a ``catchpad`` instruction. 8566If the specified ``catchpad`` is not the most-recently-entered not-yet-exited 8567funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 8568the ``catchret``'s behavior is undefined. 8569 8570Example: 8571"""""""" 8572 8573.. code-block:: text 8574 8575 catchret from %catch to label %continue 8576 8577.. _i_cleanupret: 8578 8579'``cleanupret``' Instruction 8580^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8581 8582Syntax: 8583""""""" 8584 8585:: 8586 8587 cleanupret from <value> unwind label <continue> 8588 cleanupret from <value> unwind to caller 8589 8590Overview: 8591""""""""" 8592 8593The '``cleanupret``' instruction is a terminator instruction that has 8594an optional successor. 8595 8596 8597Arguments: 8598"""""""""" 8599 8600The '``cleanupret``' instruction requires one argument, which indicates 8601which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_cleanuppad>`. 8602If the specified ``cleanuppad`` is not the most-recently-entered not-yet-exited 8603funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 8604the ``cleanupret``'s behavior is undefined. 8605 8606The '``cleanupret``' instruction also has an optional successor, ``continue``, 8607which must be the label of another basic block beginning with either a 8608``cleanuppad`` or ``catchswitch`` instruction. This unwind destination must 8609be a legal target with respect to the ``parent`` links, as described in the 8610`exception handling documentation\ <ExceptionHandling.html#wineh-constraints>`_. 8611 8612Semantics: 8613"""""""""" 8614 8615The '``cleanupret``' instruction indicates to the 8616:ref:`personality function <personalityfn>` that one 8617:ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended. 8618It transfers control to ``continue`` or unwinds out of the function. 8619 8620Example: 8621"""""""" 8622 8623.. code-block:: text 8624 8625 cleanupret from %cleanup unwind to caller 8626 cleanupret from %cleanup unwind label %continue 8627 8628.. _i_unreachable: 8629 8630'``unreachable``' Instruction 8631^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8632 8633Syntax: 8634""""""" 8635 8636:: 8637 8638 unreachable 8639 8640Overview: 8641""""""""" 8642 8643The '``unreachable``' instruction has no defined semantics. This 8644instruction is used to inform the optimizer that a particular portion of 8645the code is not reachable. This can be used to indicate that the code 8646after a no-return function cannot be reached, and other facts. 8647 8648Semantics: 8649"""""""""" 8650 8651The '``unreachable``' instruction has no defined semantics. 8652 8653.. _unaryops: 8654 8655Unary Operations 8656----------------- 8657 8658Unary operators require a single operand, execute an operation on 8659it, and produce a single value. The operand might represent multiple 8660data, as is the case with the :ref:`vector <t_vector>` data type. The 8661result value has the same type as its operand. 8662 8663.. _i_fneg: 8664 8665'``fneg``' Instruction 8666^^^^^^^^^^^^^^^^^^^^^^ 8667 8668Syntax: 8669""""""" 8670 8671:: 8672 8673 <result> = fneg [fast-math flags]* <ty> <op1> ; yields ty:result 8674 8675Overview: 8676""""""""" 8677 8678The '``fneg``' instruction returns the negation of its operand. 8679 8680Arguments: 8681"""""""""" 8682 8683The argument to the '``fneg``' instruction must be a 8684:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8685floating-point values. 8686 8687Semantics: 8688"""""""""" 8689 8690The value produced is a copy of the operand with its sign bit flipped. 8691This instruction can also take any number of :ref:`fast-math 8692flags <fastmath>`, which are optimization hints to enable otherwise 8693unsafe floating-point optimizations: 8694 8695Example: 8696"""""""" 8697 8698.. code-block:: text 8699 8700 <result> = fneg float %val ; yields float:result = -%var 8701 8702.. _binaryops: 8703 8704Binary Operations 8705----------------- 8706 8707Binary operators are used to do most of the computation in a program. 8708They require two operands of the same type, execute an operation on 8709them, and produce a single value. The operands might represent multiple 8710data, as is the case with the :ref:`vector <t_vector>` data type. The 8711result value has the same type as its operands. 8712 8713There are several different binary operators: 8714 8715.. _i_add: 8716 8717'``add``' Instruction 8718^^^^^^^^^^^^^^^^^^^^^ 8719 8720Syntax: 8721""""""" 8722 8723:: 8724 8725 <result> = add <ty> <op1>, <op2> ; yields ty:result 8726 <result> = add nuw <ty> <op1>, <op2> ; yields ty:result 8727 <result> = add nsw <ty> <op1>, <op2> ; yields ty:result 8728 <result> = add nuw nsw <ty> <op1>, <op2> ; yields ty:result 8729 8730Overview: 8731""""""""" 8732 8733The '``add``' instruction returns the sum of its two operands. 8734 8735Arguments: 8736"""""""""" 8737 8738The two arguments to the '``add``' instruction must be 8739:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8740arguments must have identical types. 8741 8742Semantics: 8743"""""""""" 8744 8745The value produced is the integer sum of the two operands. 8746 8747If the sum has unsigned overflow, the result returned is the 8748mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of 8749the result. 8750 8751Because LLVM integers use a two's complement representation, this 8752instruction is appropriate for both signed and unsigned integers. 8753 8754``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 8755respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 8756result value of the ``add`` is a :ref:`poison value <poisonvalues>` if 8757unsigned and/or signed overflow, respectively, occurs. 8758 8759Example: 8760"""""""" 8761 8762.. code-block:: text 8763 8764 <result> = add i32 4, %var ; yields i32:result = 4 + %var 8765 8766.. _i_fadd: 8767 8768'``fadd``' Instruction 8769^^^^^^^^^^^^^^^^^^^^^^ 8770 8771Syntax: 8772""""""" 8773 8774:: 8775 8776 <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8777 8778Overview: 8779""""""""" 8780 8781The '``fadd``' instruction returns the sum of its two operands. 8782 8783Arguments: 8784"""""""""" 8785 8786The two arguments to the '``fadd``' instruction must be 8787:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8788floating-point values. Both arguments must have identical types. 8789 8790Semantics: 8791"""""""""" 8792 8793The value produced is the floating-point sum of the two operands. 8794This instruction is assumed to execute in the default :ref:`floating-point 8795environment <floatenv>`. 8796This instruction can also take any number of :ref:`fast-math 8797flags <fastmath>`, which are optimization hints to enable otherwise 8798unsafe floating-point optimizations: 8799 8800Example: 8801"""""""" 8802 8803.. code-block:: text 8804 8805 <result> = fadd float 4.0, %var ; yields float:result = 4.0 + %var 8806 8807.. _i_sub: 8808 8809'``sub``' Instruction 8810^^^^^^^^^^^^^^^^^^^^^ 8811 8812Syntax: 8813""""""" 8814 8815:: 8816 8817 <result> = sub <ty> <op1>, <op2> ; yields ty:result 8818 <result> = sub nuw <ty> <op1>, <op2> ; yields ty:result 8819 <result> = sub nsw <ty> <op1>, <op2> ; yields ty:result 8820 <result> = sub nuw nsw <ty> <op1>, <op2> ; yields ty:result 8821 8822Overview: 8823""""""""" 8824 8825The '``sub``' instruction returns the difference of its two operands. 8826 8827Note that the '``sub``' instruction is used to represent the '``neg``' 8828instruction present in most other intermediate representations. 8829 8830Arguments: 8831"""""""""" 8832 8833The two arguments to the '``sub``' instruction must be 8834:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8835arguments must have identical types. 8836 8837Semantics: 8838"""""""""" 8839 8840The value produced is the integer difference of the two operands. 8841 8842If the difference has unsigned overflow, the result returned is the 8843mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of 8844the result. 8845 8846Because LLVM integers use a two's complement representation, this 8847instruction is appropriate for both signed and unsigned integers. 8848 8849``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 8850respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 8851result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if 8852unsigned and/or signed overflow, respectively, occurs. 8853 8854Example: 8855"""""""" 8856 8857.. code-block:: text 8858 8859 <result> = sub i32 4, %var ; yields i32:result = 4 - %var 8860 <result> = sub i32 0, %val ; yields i32:result = -%var 8861 8862.. _i_fsub: 8863 8864'``fsub``' Instruction 8865^^^^^^^^^^^^^^^^^^^^^^ 8866 8867Syntax: 8868""""""" 8869 8870:: 8871 8872 <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8873 8874Overview: 8875""""""""" 8876 8877The '``fsub``' instruction returns the difference of its two operands. 8878 8879Arguments: 8880"""""""""" 8881 8882The two arguments to the '``fsub``' instruction must be 8883:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8884floating-point values. Both arguments must have identical types. 8885 8886Semantics: 8887"""""""""" 8888 8889The value produced is the floating-point difference of the two operands. 8890This instruction is assumed to execute in the default :ref:`floating-point 8891environment <floatenv>`. 8892This instruction can also take any number of :ref:`fast-math 8893flags <fastmath>`, which are optimization hints to enable otherwise 8894unsafe floating-point optimizations: 8895 8896Example: 8897"""""""" 8898 8899.. code-block:: text 8900 8901 <result> = fsub float 4.0, %var ; yields float:result = 4.0 - %var 8902 <result> = fsub float -0.0, %val ; yields float:result = -%var 8903 8904.. _i_mul: 8905 8906'``mul``' Instruction 8907^^^^^^^^^^^^^^^^^^^^^ 8908 8909Syntax: 8910""""""" 8911 8912:: 8913 8914 <result> = mul <ty> <op1>, <op2> ; yields ty:result 8915 <result> = mul nuw <ty> <op1>, <op2> ; yields ty:result 8916 <result> = mul nsw <ty> <op1>, <op2> ; yields ty:result 8917 <result> = mul nuw nsw <ty> <op1>, <op2> ; yields ty:result 8918 8919Overview: 8920""""""""" 8921 8922The '``mul``' instruction returns the product of its two operands. 8923 8924Arguments: 8925"""""""""" 8926 8927The two arguments to the '``mul``' instruction must be 8928:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 8929arguments must have identical types. 8930 8931Semantics: 8932"""""""""" 8933 8934The value produced is the integer product of the two operands. 8935 8936If the result of the multiplication has unsigned overflow, the result 8937returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the 8938bit width of the result. 8939 8940Because LLVM integers use a two's complement representation, and the 8941result is the same width as the operands, this instruction returns the 8942correct result for both signed and unsigned integers. If a full product 8943(e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be 8944sign-extended or zero-extended as appropriate to the width of the full 8945product. 8946 8947``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", 8948respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the 8949result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if 8950unsigned and/or signed overflow, respectively, occurs. 8951 8952Example: 8953"""""""" 8954 8955.. code-block:: text 8956 8957 <result> = mul i32 4, %var ; yields i32:result = 4 * %var 8958 8959.. _i_fmul: 8960 8961'``fmul``' Instruction 8962^^^^^^^^^^^^^^^^^^^^^^ 8963 8964Syntax: 8965""""""" 8966 8967:: 8968 8969 <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 8970 8971Overview: 8972""""""""" 8973 8974The '``fmul``' instruction returns the product of its two operands. 8975 8976Arguments: 8977"""""""""" 8978 8979The two arguments to the '``fmul``' instruction must be 8980:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 8981floating-point values. Both arguments must have identical types. 8982 8983Semantics: 8984"""""""""" 8985 8986The value produced is the floating-point product of the two operands. 8987This instruction is assumed to execute in the default :ref:`floating-point 8988environment <floatenv>`. 8989This instruction can also take any number of :ref:`fast-math 8990flags <fastmath>`, which are optimization hints to enable otherwise 8991unsafe floating-point optimizations: 8992 8993Example: 8994"""""""" 8995 8996.. code-block:: text 8997 8998 <result> = fmul float 4.0, %var ; yields float:result = 4.0 * %var 8999 9000.. _i_udiv: 9001 9002'``udiv``' Instruction 9003^^^^^^^^^^^^^^^^^^^^^^ 9004 9005Syntax: 9006""""""" 9007 9008:: 9009 9010 <result> = udiv <ty> <op1>, <op2> ; yields ty:result 9011 <result> = udiv exact <ty> <op1>, <op2> ; yields ty:result 9012 9013Overview: 9014""""""""" 9015 9016The '``udiv``' instruction returns the quotient of its two operands. 9017 9018Arguments: 9019"""""""""" 9020 9021The two arguments to the '``udiv``' instruction must be 9022:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9023arguments must have identical types. 9024 9025Semantics: 9026"""""""""" 9027 9028The value produced is the unsigned integer quotient of the two operands. 9029 9030Note that unsigned integer division and signed integer division are 9031distinct operations; for signed integer division, use '``sdiv``'. 9032 9033Division by zero is undefined behavior. For vectors, if any element 9034of the divisor is zero, the operation has undefined behavior. 9035 9036 9037If the ``exact`` keyword is present, the result value of the ``udiv`` is 9038a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as 9039such, "((a udiv exact b) mul b) == a"). 9040 9041Example: 9042"""""""" 9043 9044.. code-block:: text 9045 9046 <result> = udiv i32 4, %var ; yields i32:result = 4 / %var 9047 9048.. _i_sdiv: 9049 9050'``sdiv``' Instruction 9051^^^^^^^^^^^^^^^^^^^^^^ 9052 9053Syntax: 9054""""""" 9055 9056:: 9057 9058 <result> = sdiv <ty> <op1>, <op2> ; yields ty:result 9059 <result> = sdiv exact <ty> <op1>, <op2> ; yields ty:result 9060 9061Overview: 9062""""""""" 9063 9064The '``sdiv``' instruction returns the quotient of its two operands. 9065 9066Arguments: 9067"""""""""" 9068 9069The two arguments to the '``sdiv``' instruction must be 9070:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9071arguments must have identical types. 9072 9073Semantics: 9074"""""""""" 9075 9076The value produced is the signed integer quotient of the two operands 9077rounded towards zero. 9078 9079Note that signed integer division and unsigned integer division are 9080distinct operations; for unsigned integer division, use '``udiv``'. 9081 9082Division by zero is undefined behavior. For vectors, if any element 9083of the divisor is zero, the operation has undefined behavior. 9084Overflow also leads to undefined behavior; this is a rare case, but can 9085occur, for example, by doing a 32-bit division of -2147483648 by -1. 9086 9087If the ``exact`` keyword is present, the result value of the ``sdiv`` is 9088a :ref:`poison value <poisonvalues>` if the result would be rounded. 9089 9090Example: 9091"""""""" 9092 9093.. code-block:: text 9094 9095 <result> = sdiv i32 4, %var ; yields i32:result = 4 / %var 9096 9097.. _i_fdiv: 9098 9099'``fdiv``' Instruction 9100^^^^^^^^^^^^^^^^^^^^^^ 9101 9102Syntax: 9103""""""" 9104 9105:: 9106 9107 <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 9108 9109Overview: 9110""""""""" 9111 9112The '``fdiv``' instruction returns the quotient of its two operands. 9113 9114Arguments: 9115"""""""""" 9116 9117The two arguments to the '``fdiv``' instruction must be 9118:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 9119floating-point values. Both arguments must have identical types. 9120 9121Semantics: 9122"""""""""" 9123 9124The value produced is the floating-point quotient of the two operands. 9125This instruction is assumed to execute in the default :ref:`floating-point 9126environment <floatenv>`. 9127This instruction can also take any number of :ref:`fast-math 9128flags <fastmath>`, which are optimization hints to enable otherwise 9129unsafe floating-point optimizations: 9130 9131Example: 9132"""""""" 9133 9134.. code-block:: text 9135 9136 <result> = fdiv float 4.0, %var ; yields float:result = 4.0 / %var 9137 9138.. _i_urem: 9139 9140'``urem``' Instruction 9141^^^^^^^^^^^^^^^^^^^^^^ 9142 9143Syntax: 9144""""""" 9145 9146:: 9147 9148 <result> = urem <ty> <op1>, <op2> ; yields ty:result 9149 9150Overview: 9151""""""""" 9152 9153The '``urem``' instruction returns the remainder from the unsigned 9154division of its two arguments. 9155 9156Arguments: 9157"""""""""" 9158 9159The two arguments to the '``urem``' instruction must be 9160:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9161arguments must have identical types. 9162 9163Semantics: 9164"""""""""" 9165 9166This instruction returns the unsigned integer *remainder* of a division. 9167This instruction always performs an unsigned division to get the 9168remainder. 9169 9170Note that unsigned integer remainder and signed integer remainder are 9171distinct operations; for signed integer remainder, use '``srem``'. 9172 9173Taking the remainder of a division by zero is undefined behavior. 9174For vectors, if any element of the divisor is zero, the operation has 9175undefined behavior. 9176 9177Example: 9178"""""""" 9179 9180.. code-block:: text 9181 9182 <result> = urem i32 4, %var ; yields i32:result = 4 % %var 9183 9184.. _i_srem: 9185 9186'``srem``' Instruction 9187^^^^^^^^^^^^^^^^^^^^^^ 9188 9189Syntax: 9190""""""" 9191 9192:: 9193 9194 <result> = srem <ty> <op1>, <op2> ; yields ty:result 9195 9196Overview: 9197""""""""" 9198 9199The '``srem``' instruction returns the remainder from the signed 9200division of its two operands. This instruction can also take 9201:ref:`vector <t_vector>` versions of the values in which case the elements 9202must be integers. 9203 9204Arguments: 9205"""""""""" 9206 9207The two arguments to the '``srem``' instruction must be 9208:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9209arguments must have identical types. 9210 9211Semantics: 9212"""""""""" 9213 9214This instruction returns the *remainder* of a division (where the result 9215is either zero or has the same sign as the dividend, ``op1``), not the 9216*modulo* operator (where the result is either zero or has the same sign 9217as the divisor, ``op2``) of a value. For more information about the 9218difference, see `The Math 9219Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a 9220table of how this is implemented in various languages, please see 9221`Wikipedia: modulo 9222operation <http://en.wikipedia.org/wiki/Modulo_operation>`_. 9223 9224Note that signed integer remainder and unsigned integer remainder are 9225distinct operations; for unsigned integer remainder, use '``urem``'. 9226 9227Taking the remainder of a division by zero is undefined behavior. 9228For vectors, if any element of the divisor is zero, the operation has 9229undefined behavior. 9230Overflow also leads to undefined behavior; this is a rare case, but can 9231occur, for example, by taking the remainder of a 32-bit division of 9232-2147483648 by -1. (The remainder doesn't actually overflow, but this 9233rule lets srem be implemented using instructions that return both the 9234result of the division and the remainder.) 9235 9236Example: 9237"""""""" 9238 9239.. code-block:: text 9240 9241 <result> = srem i32 4, %var ; yields i32:result = 4 % %var 9242 9243.. _i_frem: 9244 9245'``frem``' Instruction 9246^^^^^^^^^^^^^^^^^^^^^^ 9247 9248Syntax: 9249""""""" 9250 9251:: 9252 9253 <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result 9254 9255Overview: 9256""""""""" 9257 9258The '``frem``' instruction returns the remainder from the division of 9259its two operands. 9260 9261Arguments: 9262"""""""""" 9263 9264The two arguments to the '``frem``' instruction must be 9265:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of 9266floating-point values. Both arguments must have identical types. 9267 9268Semantics: 9269"""""""""" 9270 9271The value produced is the floating-point remainder of the two operands. 9272This is the same output as a libm '``fmod``' function, but without any 9273possibility of setting ``errno``. The remainder has the same sign as the 9274dividend. 9275This instruction is assumed to execute in the default :ref:`floating-point 9276environment <floatenv>`. 9277This instruction can also take any number of :ref:`fast-math 9278flags <fastmath>`, which are optimization hints to enable otherwise 9279unsafe floating-point optimizations: 9280 9281Example: 9282"""""""" 9283 9284.. code-block:: text 9285 9286 <result> = frem float 4.0, %var ; yields float:result = 4.0 % %var 9287 9288.. _bitwiseops: 9289 9290Bitwise Binary Operations 9291------------------------- 9292 9293Bitwise binary operators are used to do various forms of bit-twiddling 9294in a program. They are generally very efficient instructions and can 9295commonly be strength reduced from other instructions. They require two 9296operands of the same type, execute an operation on them, and produce a 9297single value. The resulting value is the same type as its operands. 9298 9299.. _i_shl: 9300 9301'``shl``' Instruction 9302^^^^^^^^^^^^^^^^^^^^^ 9303 9304Syntax: 9305""""""" 9306 9307:: 9308 9309 <result> = shl <ty> <op1>, <op2> ; yields ty:result 9310 <result> = shl nuw <ty> <op1>, <op2> ; yields ty:result 9311 <result> = shl nsw <ty> <op1>, <op2> ; yields ty:result 9312 <result> = shl nuw nsw <ty> <op1>, <op2> ; yields ty:result 9313 9314Overview: 9315""""""""" 9316 9317The '``shl``' instruction returns the first operand shifted to the left 9318a specified number of bits. 9319 9320Arguments: 9321"""""""""" 9322 9323Both arguments to the '``shl``' instruction must be the same 9324:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 9325'``op2``' is treated as an unsigned value. 9326 9327Semantics: 9328"""""""""" 9329 9330The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`, 9331where ``n`` is the width of the result. If ``op2`` is (statically or 9332dynamically) equal to or larger than the number of bits in 9333``op1``, this instruction returns a :ref:`poison value <poisonvalues>`. 9334If the arguments are vectors, each vector element of ``op1`` is shifted 9335by the corresponding shift amount in ``op2``. 9336 9337If the ``nuw`` keyword is present, then the shift produces a poison 9338value if it shifts out any non-zero bits. 9339If the ``nsw`` keyword is present, then the shift produces a poison 9340value if it shifts out any bits that disagree with the resultant sign bit. 9341 9342Example: 9343"""""""" 9344 9345.. code-block:: text 9346 9347 <result> = shl i32 4, %var ; yields i32: 4 << %var 9348 <result> = shl i32 4, 2 ; yields i32: 16 9349 <result> = shl i32 1, 10 ; yields i32: 1024 9350 <result> = shl i32 1, 32 ; undefined 9351 <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4> 9352 9353.. _i_lshr: 9354 9355 9356'``lshr``' Instruction 9357^^^^^^^^^^^^^^^^^^^^^^ 9358 9359Syntax: 9360""""""" 9361 9362:: 9363 9364 <result> = lshr <ty> <op1>, <op2> ; yields ty:result 9365 <result> = lshr exact <ty> <op1>, <op2> ; yields ty:result 9366 9367Overview: 9368""""""""" 9369 9370The '``lshr``' instruction (logical shift right) returns the first 9371operand shifted to the right a specified number of bits with zero fill. 9372 9373Arguments: 9374"""""""""" 9375 9376Both arguments to the '``lshr``' instruction must be the same 9377:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 9378'``op2``' is treated as an unsigned value. 9379 9380Semantics: 9381"""""""""" 9382 9383This instruction always performs a logical shift right operation. The 9384most significant bits of the result will be filled with zero bits after 9385the shift. If ``op2`` is (statically or dynamically) equal to or larger 9386than the number of bits in ``op1``, this instruction returns a :ref:`poison 9387value <poisonvalues>`. If the arguments are vectors, each vector element 9388of ``op1`` is shifted by the corresponding shift amount in ``op2``. 9389 9390If the ``exact`` keyword is present, the result value of the ``lshr`` is 9391a poison value if any of the bits shifted out are non-zero. 9392 9393Example: 9394"""""""" 9395 9396.. code-block:: text 9397 9398 <result> = lshr i32 4, 1 ; yields i32:result = 2 9399 <result> = lshr i32 4, 2 ; yields i32:result = 1 9400 <result> = lshr i8 4, 3 ; yields i8:result = 0 9401 <result> = lshr i8 -2, 1 ; yields i8:result = 0x7F 9402 <result> = lshr i32 1, 32 ; undefined 9403 <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1> 9404 9405.. _i_ashr: 9406 9407'``ashr``' Instruction 9408^^^^^^^^^^^^^^^^^^^^^^ 9409 9410Syntax: 9411""""""" 9412 9413:: 9414 9415 <result> = ashr <ty> <op1>, <op2> ; yields ty:result 9416 <result> = ashr exact <ty> <op1>, <op2> ; yields ty:result 9417 9418Overview: 9419""""""""" 9420 9421The '``ashr``' instruction (arithmetic shift right) returns the first 9422operand shifted to the right a specified number of bits with sign 9423extension. 9424 9425Arguments: 9426"""""""""" 9427 9428Both arguments to the '``ashr``' instruction must be the same 9429:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. 9430'``op2``' is treated as an unsigned value. 9431 9432Semantics: 9433"""""""""" 9434 9435This instruction always performs an arithmetic shift right operation, 9436The most significant bits of the result will be filled with the sign bit 9437of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger 9438than the number of bits in ``op1``, this instruction returns a :ref:`poison 9439value <poisonvalues>`. If the arguments are vectors, each vector element 9440of ``op1`` is shifted by the corresponding shift amount in ``op2``. 9441 9442If the ``exact`` keyword is present, the result value of the ``ashr`` is 9443a poison value if any of the bits shifted out are non-zero. 9444 9445Example: 9446"""""""" 9447 9448.. code-block:: text 9449 9450 <result> = ashr i32 4, 1 ; yields i32:result = 2 9451 <result> = ashr i32 4, 2 ; yields i32:result = 1 9452 <result> = ashr i8 4, 3 ; yields i8:result = 0 9453 <result> = ashr i8 -2, 1 ; yields i8:result = -1 9454 <result> = ashr i32 1, 32 ; undefined 9455 <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0> 9456 9457.. _i_and: 9458 9459'``and``' Instruction 9460^^^^^^^^^^^^^^^^^^^^^ 9461 9462Syntax: 9463""""""" 9464 9465:: 9466 9467 <result> = and <ty> <op1>, <op2> ; yields ty:result 9468 9469Overview: 9470""""""""" 9471 9472The '``and``' instruction returns the bitwise logical and of its two 9473operands. 9474 9475Arguments: 9476"""""""""" 9477 9478The two arguments to the '``and``' instruction must be 9479:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9480arguments must have identical types. 9481 9482Semantics: 9483"""""""""" 9484 9485The truth table used for the '``and``' instruction is: 9486 9487+-----+-----+-----+ 9488| In0 | In1 | Out | 9489+-----+-----+-----+ 9490| 0 | 0 | 0 | 9491+-----+-----+-----+ 9492| 0 | 1 | 0 | 9493+-----+-----+-----+ 9494| 1 | 0 | 0 | 9495+-----+-----+-----+ 9496| 1 | 1 | 1 | 9497+-----+-----+-----+ 9498 9499Example: 9500"""""""" 9501 9502.. code-block:: text 9503 9504 <result> = and i32 4, %var ; yields i32:result = 4 & %var 9505 <result> = and i32 15, 40 ; yields i32:result = 8 9506 <result> = and i32 4, 8 ; yields i32:result = 0 9507 9508.. _i_or: 9509 9510'``or``' Instruction 9511^^^^^^^^^^^^^^^^^^^^ 9512 9513Syntax: 9514""""""" 9515 9516:: 9517 9518 <result> = or <ty> <op1>, <op2> ; yields ty:result 9519 9520Overview: 9521""""""""" 9522 9523The '``or``' instruction returns the bitwise logical inclusive or of its 9524two operands. 9525 9526Arguments: 9527"""""""""" 9528 9529The two arguments to the '``or``' instruction must be 9530:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9531arguments must have identical types. 9532 9533Semantics: 9534"""""""""" 9535 9536The truth table used for the '``or``' instruction is: 9537 9538+-----+-----+-----+ 9539| In0 | In1 | Out | 9540+-----+-----+-----+ 9541| 0 | 0 | 0 | 9542+-----+-----+-----+ 9543| 0 | 1 | 1 | 9544+-----+-----+-----+ 9545| 1 | 0 | 1 | 9546+-----+-----+-----+ 9547| 1 | 1 | 1 | 9548+-----+-----+-----+ 9549 9550Example: 9551"""""""" 9552 9553:: 9554 9555 <result> = or i32 4, %var ; yields i32:result = 4 | %var 9556 <result> = or i32 15, 40 ; yields i32:result = 47 9557 <result> = or i32 4, 8 ; yields i32:result = 12 9558 9559.. _i_xor: 9560 9561'``xor``' Instruction 9562^^^^^^^^^^^^^^^^^^^^^ 9563 9564Syntax: 9565""""""" 9566 9567:: 9568 9569 <result> = xor <ty> <op1>, <op2> ; yields ty:result 9570 9571Overview: 9572""""""""" 9573 9574The '``xor``' instruction returns the bitwise logical exclusive or of 9575its two operands. The ``xor`` is used to implement the "one's 9576complement" operation, which is the "~" operator in C. 9577 9578Arguments: 9579"""""""""" 9580 9581The two arguments to the '``xor``' instruction must be 9582:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both 9583arguments must have identical types. 9584 9585Semantics: 9586"""""""""" 9587 9588The truth table used for the '``xor``' instruction is: 9589 9590+-----+-----+-----+ 9591| In0 | In1 | Out | 9592+-----+-----+-----+ 9593| 0 | 0 | 0 | 9594+-----+-----+-----+ 9595| 0 | 1 | 1 | 9596+-----+-----+-----+ 9597| 1 | 0 | 1 | 9598+-----+-----+-----+ 9599| 1 | 1 | 0 | 9600+-----+-----+-----+ 9601 9602Example: 9603"""""""" 9604 9605.. code-block:: text 9606 9607 <result> = xor i32 4, %var ; yields i32:result = 4 ^ %var 9608 <result> = xor i32 15, 40 ; yields i32:result = 39 9609 <result> = xor i32 4, 8 ; yields i32:result = 12 9610 <result> = xor i32 %V, -1 ; yields i32:result = ~%V 9611 9612Vector Operations 9613----------------- 9614 9615LLVM supports several instructions to represent vector operations in a 9616target-independent manner. These instructions cover the element-access 9617and vector-specific operations needed to process vectors effectively. 9618While LLVM does directly support these vector operations, many 9619sophisticated algorithms will want to use target-specific intrinsics to 9620take full advantage of a specific target. 9621 9622.. _i_extractelement: 9623 9624'``extractelement``' Instruction 9625^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9626 9627Syntax: 9628""""""" 9629 9630:: 9631 9632 <result> = extractelement <n x <ty>> <val>, <ty2> <idx> ; yields <ty> 9633 <result> = extractelement <vscale x n x <ty>> <val>, <ty2> <idx> ; yields <ty> 9634 9635Overview: 9636""""""""" 9637 9638The '``extractelement``' instruction extracts a single scalar element 9639from a vector at a specified index. 9640 9641Arguments: 9642"""""""""" 9643 9644The first operand of an '``extractelement``' instruction is a value of 9645:ref:`vector <t_vector>` type. The second operand is an index indicating 9646the position from which to extract the element. The index may be a 9647variable of any integer type. 9648 9649Semantics: 9650"""""""""" 9651 9652The result is a scalar of the same type as the element type of ``val``. 9653Its value is the value at position ``idx`` of ``val``. If ``idx`` 9654exceeds the length of ``val`` for a fixed-length vector, the result is a 9655:ref:`poison value <poisonvalues>`. For a scalable vector, if the value 9656of ``idx`` exceeds the runtime length of the vector, the result is a 9657:ref:`poison value <poisonvalues>`. 9658 9659Example: 9660"""""""" 9661 9662.. code-block:: text 9663 9664 <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32 9665 9666.. _i_insertelement: 9667 9668'``insertelement``' Instruction 9669^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9670 9671Syntax: 9672""""""" 9673 9674:: 9675 9676 <result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <n x <ty>> 9677 <result> = insertelement <vscale x n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <vscale x n x <ty>> 9678 9679Overview: 9680""""""""" 9681 9682The '``insertelement``' instruction inserts a scalar element into a 9683vector at a specified index. 9684 9685Arguments: 9686"""""""""" 9687 9688The first operand of an '``insertelement``' instruction is a value of 9689:ref:`vector <t_vector>` type. The second operand is a scalar value whose 9690type must equal the element type of the first operand. The third operand 9691is an index indicating the position at which to insert the value. The 9692index may be a variable of any integer type. 9693 9694Semantics: 9695"""""""""" 9696 9697The result is a vector of the same type as ``val``. Its element values 9698are those of ``val`` except at position ``idx``, where it gets the value 9699``elt``. If ``idx`` exceeds the length of ``val`` for a fixed-length vector, 9700the result is a :ref:`poison value <poisonvalues>`. For a scalable vector, 9701if the value of ``idx`` exceeds the runtime length of the vector, the result 9702is a :ref:`poison value <poisonvalues>`. 9703 9704Example: 9705"""""""" 9706 9707.. code-block:: text 9708 9709 <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32> 9710 9711.. _i_shufflevector: 9712 9713'``shufflevector``' Instruction 9714^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9715 9716Syntax: 9717""""""" 9718 9719:: 9720 9721 <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>> 9722 <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>> 9723 9724Overview: 9725""""""""" 9726 9727The '``shufflevector``' instruction constructs a permutation of elements 9728from two input vectors, returning a vector with the same element type as 9729the input and length that is the same as the shuffle mask. 9730 9731Arguments: 9732"""""""""" 9733 9734The first two operands of a '``shufflevector``' instruction are vectors 9735with the same type. The third argument is a shuffle mask vector constant 9736whose element type is ``i32``. The mask vector elements must be constant 9737integers or ``undef`` values. The result of the instruction is a vector 9738whose length is the same as the shuffle mask and whose element type is the 9739same as the element type of the first two operands. 9740 9741Semantics: 9742"""""""""" 9743 9744The elements of the two input vectors are numbered from left to right 9745across both of the vectors. For each element of the result vector, the 9746shuffle mask selects an element from one of the input vectors to copy 9747to the result. Non-negative elements in the mask represent an index 9748into the concatenated pair of input vectors. 9749 9750If the shuffle mask is undefined, the result vector is undefined. If 9751the shuffle mask selects an undefined element from one of the input 9752vectors, the resulting element is undefined. An undefined element 9753in the mask vector specifies that the resulting element is undefined. 9754An undefined element in the mask vector prevents a poisoned vector 9755element from propagating. 9756 9757For scalable vectors, the only valid mask values at present are 9758``zeroinitializer`` and ``undef``, since we cannot write all indices as 9759literals for a vector with a length unknown at compile time. 9760 9761Example: 9762"""""""" 9763 9764.. code-block:: text 9765 9766 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 9767 <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32> 9768 <result> = shufflevector <4 x i32> %v1, <4 x i32> undef, 9769 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle. 9770 <result> = shufflevector <8 x i32> %v1, <8 x i32> undef, 9771 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> 9772 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, 9773 <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32> 9774 9775Aggregate Operations 9776-------------------- 9777 9778LLVM supports several instructions for working with 9779:ref:`aggregate <t_aggregate>` values. 9780 9781.. _i_extractvalue: 9782 9783'``extractvalue``' Instruction 9784^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9785 9786Syntax: 9787""""""" 9788 9789:: 9790 9791 <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}* 9792 9793Overview: 9794""""""""" 9795 9796The '``extractvalue``' instruction extracts the value of a member field 9797from an :ref:`aggregate <t_aggregate>` value. 9798 9799Arguments: 9800"""""""""" 9801 9802The first operand of an '``extractvalue``' instruction is a value of 9803:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The other operands are 9804constant indices to specify which value to extract in a similar manner 9805as indices in a '``getelementptr``' instruction. 9806 9807The major differences to ``getelementptr`` indexing are: 9808 9809- Since the value being indexed is not a pointer, the first index is 9810 omitted and assumed to be zero. 9811- At least one index must be specified. 9812- Not only struct indices but also array indices must be in bounds. 9813 9814Semantics: 9815"""""""""" 9816 9817The result is the value at the position in the aggregate specified by 9818the index operands. 9819 9820Example: 9821"""""""" 9822 9823.. code-block:: text 9824 9825 <result> = extractvalue {i32, float} %agg, 0 ; yields i32 9826 9827.. _i_insertvalue: 9828 9829'``insertvalue``' Instruction 9830^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9831 9832Syntax: 9833""""""" 9834 9835:: 9836 9837 <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type> 9838 9839Overview: 9840""""""""" 9841 9842The '``insertvalue``' instruction inserts a value into a member field in 9843an :ref:`aggregate <t_aggregate>` value. 9844 9845Arguments: 9846"""""""""" 9847 9848The first operand of an '``insertvalue``' instruction is a value of 9849:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The second operand is 9850a first-class value to insert. The following operands are constant 9851indices indicating the position at which to insert the value in a 9852similar manner as indices in a '``extractvalue``' instruction. The value 9853to insert must have the same type as the value identified by the 9854indices. 9855 9856Semantics: 9857"""""""""" 9858 9859The result is an aggregate of the same type as ``val``. Its value is 9860that of ``val`` except that the value at the position specified by the 9861indices is that of ``elt``. 9862 9863Example: 9864"""""""" 9865 9866.. code-block:: llvm 9867 9868 %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef} 9869 %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val} 9870 %agg3 = insertvalue {i32, {float}} undef, float %val, 1, 0 ; yields {i32 undef, {float %val}} 9871 9872.. _memoryops: 9873 9874Memory Access and Addressing Operations 9875--------------------------------------- 9876 9877A key design point of an SSA-based representation is how it represents 9878memory. In LLVM, no memory locations are in SSA form, which makes things 9879very simple. This section describes how to read, write, and allocate 9880memory in LLVM. 9881 9882.. _i_alloca: 9883 9884'``alloca``' Instruction 9885^^^^^^^^^^^^^^^^^^^^^^^^ 9886 9887Syntax: 9888""""""" 9889 9890:: 9891 9892 <result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] [, addrspace(<num>)] ; yields type addrspace(num)*:result 9893 9894Overview: 9895""""""""" 9896 9897The '``alloca``' instruction allocates memory on the stack frame of the 9898currently executing function, to be automatically released when this 9899function returns to its caller. If the address space is not explicitly 9900specified, the object is allocated in the alloca address space from the 9901:ref:`datalayout string<langref_datalayout>`. 9902 9903Arguments: 9904"""""""""" 9905 9906The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements`` 9907bytes of memory on the runtime stack, returning a pointer of the 9908appropriate type to the program. If "NumElements" is specified, it is 9909the number of elements allocated, otherwise "NumElements" is defaulted 9910to be one. If a constant alignment is specified, the value result of the 9911allocation is guaranteed to be aligned to at least that boundary. The 9912alignment may not be greater than ``1 << 32``. If not specified, or if 9913zero, the target can choose to align the allocation on any convenient 9914boundary compatible with the type. 9915 9916'``type``' may be any sized type. 9917 9918Semantics: 9919"""""""""" 9920 9921Memory is allocated; a pointer is returned. The allocated memory is 9922uninitialized, and loading from uninitialized memory produces an undefined 9923value. The operation itself is undefined if there is insufficient stack 9924space for the allocation.'``alloca``'d memory is automatically released 9925when the function returns. The '``alloca``' instruction is commonly used 9926to represent automatic variables that must have an address available. When 9927the function returns (either with the ``ret`` or ``resume`` instructions), 9928the memory is reclaimed. Allocating zero bytes is legal, but the returned 9929pointer may not be unique. The order in which memory is allocated (ie., 9930which way the stack grows) is not specified. 9931 9932Note that '``alloca``' outside of the alloca address space from the 9933:ref:`datalayout string<langref_datalayout>` is meaningful only if the 9934target has assigned it a semantics. 9935 9936If the returned pointer is used by :ref:`llvm.lifetime.start <int_lifestart>`, 9937the returned object is initially dead. 9938See :ref:`llvm.lifetime.start <int_lifestart>` and 9939:ref:`llvm.lifetime.end <int_lifeend>` for the precise semantics of 9940lifetime-manipulating intrinsics. 9941 9942Example: 9943"""""""" 9944 9945.. code-block:: llvm 9946 9947 %ptr = alloca i32 ; yields ptr 9948 %ptr = alloca i32, i32 4 ; yields ptr 9949 %ptr = alloca i32, i32 4, align 1024 ; yields ptr 9950 %ptr = alloca i32, align 1024 ; yields ptr 9951 9952.. _i_load: 9953 9954'``load``' Instruction 9955^^^^^^^^^^^^^^^^^^^^^^ 9956 9957Syntax: 9958""""""" 9959 9960:: 9961 9962 <result> = load [volatile] <ty>, ptr <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>] 9963 <result> = load atomic [volatile] <ty>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>] 9964 !<nontemp_node> = !{ i32 1 } 9965 !<empty_node> = !{} 9966 !<deref_bytes_node> = !{ i64 <dereferenceable_bytes> } 9967 !<align_node> = !{ i64 <value_alignment> } 9968 9969Overview: 9970""""""""" 9971 9972The '``load``' instruction is used to read from memory. 9973 9974Arguments: 9975"""""""""" 9976 9977The argument to the ``load`` instruction specifies the memory address from which 9978to load. The type specified must be a :ref:`first class <t_firstclass>` type of 9979known size (i.e. not containing an :ref:`opaque structural type <t_opaque>`). If 9980the ``load`` is marked as ``volatile``, then the optimizer is not allowed to 9981modify the number or order of execution of this ``load`` with other 9982:ref:`volatile operations <volatile>`. 9983 9984If the ``load`` is marked as ``atomic``, it takes an extra :ref:`ordering 9985<ordering>` and optional ``syncscope("<target-scope>")`` argument. The 9986``release`` and ``acq_rel`` orderings are not valid on ``load`` instructions. 9987Atomic loads produce :ref:`defined <memmodel>` results when they may see 9988multiple atomic stores. The type of the pointee must be an integer, pointer, or 9989floating-point type whose bit width is a power of two greater than or equal to 9990eight and less than or equal to a target-specific size limit. ``align`` must be 9991explicitly specified on atomic loads, and the load has undefined behavior if the 9992alignment is not set to a value which is at least the size in bytes of the 9993pointee. ``!nontemporal`` does not have any defined semantics for atomic loads. 9994 9995The optional constant ``align`` argument specifies the alignment of the 9996operation (that is, the alignment of the memory address). A value of 0 9997or an omitted ``align`` argument means that the operation has the ABI 9998alignment for the target. It is the responsibility of the code emitter 9999to ensure that the alignment information is correct. Overestimating the 10000alignment results in undefined behavior. Underestimating the alignment 10001may produce less efficient code. An alignment of 1 is always safe. The 10002maximum possible alignment is ``1 << 32``. An alignment value higher 10003than the size of the loaded type implies memory up to the alignment 10004value bytes can be safely loaded without trapping in the default 10005address space. Access of the high bytes can interfere with debugging 10006tools, so should not be accessed if the function has the 10007``sanitize_thread`` or ``sanitize_address`` attributes. 10008 10009The optional ``!nontemporal`` metadata must reference a single 10010metadata name ``<nontemp_node>`` corresponding to a metadata node with one 10011``i32`` entry of value 1. The existence of the ``!nontemporal`` 10012metadata on the instruction tells the optimizer and code generator 10013that this load is not expected to be reused in the cache. The code 10014generator may select special instructions to save cache bandwidth, such 10015as the ``MOVNT`` instruction on x86. 10016 10017The optional ``!invariant.load`` metadata must reference a single 10018metadata name ``<empty_node>`` corresponding to a metadata node with no 10019entries. If a load instruction tagged with the ``!invariant.load`` 10020metadata is executed, the memory location referenced by the load has 10021to contain the same value at all points in the program where the 10022memory location is dereferenceable; otherwise, the behavior is 10023undefined. 10024 10025The optional ``!invariant.group`` metadata must reference a single metadata name 10026 ``<empty_node>`` corresponding to a metadata node with no entries. 10027 See ``invariant.group`` metadata :ref:`invariant.group <md_invariant.group>`. 10028 10029The optional ``!nonnull`` metadata must reference a single 10030metadata name ``<empty_node>`` corresponding to a metadata node with no 10031entries. The existence of the ``!nonnull`` metadata on the 10032instruction tells the optimizer that the value loaded is known to 10033never be null. If the value is null at runtime, the behavior is undefined. 10034This is analogous to the ``nonnull`` attribute on parameters and return 10035values. This metadata can only be applied to loads of a pointer type. 10036 10037The optional ``!dereferenceable`` metadata must reference a single metadata 10038name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64`` 10039entry. 10040See ``dereferenceable`` metadata :ref:`dereferenceable <md_dereferenceable>`. 10041 10042The optional ``!dereferenceable_or_null`` metadata must reference a single 10043metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one 10044``i64`` entry. 10045See ``dereferenceable_or_null`` metadata :ref:`dereferenceable_or_null 10046<md_dereferenceable_or_null>`. 10047 10048The optional ``!align`` metadata must reference a single metadata name 10049``<align_node>`` corresponding to a metadata node with one ``i64`` entry. 10050The existence of the ``!align`` metadata on the instruction tells the 10051optimizer that the value loaded is known to be aligned to a boundary specified 10052by the integer value in the metadata node. The alignment must be a power of 2. 10053This is analogous to the ''align'' attribute on parameters and return values. 10054This metadata can only be applied to loads of a pointer type. If the returned 10055value is not appropriately aligned at runtime, the behavior is undefined. 10056 10057The optional ``!noundef`` metadata must reference a single metadata name 10058``<empty_node>`` corresponding to a node with no entries. The existence of 10059``!noundef`` metadata on the instruction tells the optimizer that the value 10060loaded is known to be :ref:`well defined <welldefinedvalues>`. 10061If the value isn't well defined, the behavior is undefined. 10062 10063Semantics: 10064"""""""""" 10065 10066The location of memory pointed to is loaded. If the value being loaded 10067is of scalar type then the number of bytes read does not exceed the 10068minimum number of bytes needed to hold all bits of the type. For 10069example, loading an ``i24`` reads at most three bytes. When loading a 10070value of a type like ``i20`` with a size that is not an integral number 10071of bytes, the result is undefined if the value was not originally 10072written using a store of the same type. 10073If the value being loaded is of aggregate type, the bytes that correspond to 10074padding may be accessed but are ignored, because it is impossible to observe 10075padding from the loaded aggregate value. 10076If ``<pointer>`` is not a well-defined value, the behavior is undefined. 10077 10078Examples: 10079""""""""" 10080 10081.. code-block:: llvm 10082 10083 %ptr = alloca i32 ; yields ptr 10084 store i32 3, ptr %ptr ; yields void 10085 %val = load i32, ptr %ptr ; yields i32:val = i32 3 10086 10087.. _i_store: 10088 10089'``store``' Instruction 10090^^^^^^^^^^^^^^^^^^^^^^^ 10091 10092Syntax: 10093""""""" 10094 10095:: 10096 10097 store [volatile] <ty> <value>, ptr <pointer>[, align <alignment>][, !nontemporal !<nontemp_node>][, !invariant.group !<empty_node>] ; yields void 10098 store atomic [volatile] <ty> <value>, ptr <pointer> [syncscope("<target-scope>")] <ordering>, align <alignment> [, !invariant.group !<empty_node>] ; yields void 10099 !<nontemp_node> = !{ i32 1 } 10100 !<empty_node> = !{} 10101 10102Overview: 10103""""""""" 10104 10105The '``store``' instruction is used to write to memory. 10106 10107Arguments: 10108"""""""""" 10109 10110There are two arguments to the ``store`` instruction: a value to store and an 10111address at which to store it. The type of the ``<pointer>`` operand must be a 10112pointer to the :ref:`first class <t_firstclass>` type of the ``<value>`` 10113operand. If the ``store`` is marked as ``volatile``, then the optimizer is not 10114allowed to modify the number or order of execution of this ``store`` with other 10115:ref:`volatile operations <volatile>`. Only values of :ref:`first class 10116<t_firstclass>` types of known size (i.e. not containing an :ref:`opaque 10117structural type <t_opaque>`) can be stored. 10118 10119If the ``store`` is marked as ``atomic``, it takes an extra :ref:`ordering 10120<ordering>` and optional ``syncscope("<target-scope>")`` argument. The 10121``acquire`` and ``acq_rel`` orderings aren't valid on ``store`` instructions. 10122Atomic loads produce :ref:`defined <memmodel>` results when they may see 10123multiple atomic stores. The type of the pointee must be an integer, pointer, or 10124floating-point type whose bit width is a power of two greater than or equal to 10125eight and less than or equal to a target-specific size limit. ``align`` must be 10126explicitly specified on atomic stores, and the store has undefined behavior if 10127the alignment is not set to a value which is at least the size in bytes of the 10128pointee. ``!nontemporal`` does not have any defined semantics for atomic stores. 10129 10130The optional constant ``align`` argument specifies the alignment of the 10131operation (that is, the alignment of the memory address). A value of 0 10132or an omitted ``align`` argument means that the operation has the ABI 10133alignment for the target. It is the responsibility of the code emitter 10134to ensure that the alignment information is correct. Overestimating the 10135alignment results in undefined behavior. Underestimating the 10136alignment may produce less efficient code. An alignment of 1 is always 10137safe. The maximum possible alignment is ``1 << 32``. An alignment 10138value higher than the size of the stored type implies memory up to the 10139alignment value bytes can be stored to without trapping in the default 10140address space. Storing to the higher bytes however may result in data 10141races if another thread can access the same address. Introducing a 10142data race is not allowed. Storing to the extra bytes is not allowed 10143even in situations where a data race is known to not exist if the 10144function has the ``sanitize_address`` attribute. 10145 10146The optional ``!nontemporal`` metadata must reference a single metadata 10147name ``<nontemp_node>`` corresponding to a metadata node with one ``i32`` entry 10148of value 1. The existence of the ``!nontemporal`` metadata on the instruction 10149tells the optimizer and code generator that this load is not expected to 10150be reused in the cache. The code generator may select special 10151instructions to save cache bandwidth, such as the ``MOVNT`` instruction on 10152x86. 10153 10154The optional ``!invariant.group`` metadata must reference a 10155single metadata name ``<empty_node>``. See ``invariant.group`` metadata. 10156 10157Semantics: 10158"""""""""" 10159 10160The contents of memory are updated to contain ``<value>`` at the 10161location specified by the ``<pointer>`` operand. If ``<value>`` is 10162of scalar type then the number of bytes written does not exceed the 10163minimum number of bytes needed to hold all bits of the type. For 10164example, storing an ``i24`` writes at most three bytes. When writing a 10165value of a type like ``i20`` with a size that is not an integral number 10166of bytes, it is unspecified what happens to the extra bits that do not 10167belong to the type, but they will typically be overwritten. 10168If ``<value>`` is of aggregate type, padding is filled with 10169:ref:`undef <undefvalues>`. 10170If ``<pointer>`` is not a well-defined value, the behavior is undefined. 10171 10172Example: 10173"""""""" 10174 10175.. code-block:: llvm 10176 10177 %ptr = alloca i32 ; yields ptr 10178 store i32 3, ptr %ptr ; yields void 10179 %val = load i32, ptr %ptr ; yields i32:val = i32 3 10180 10181.. _i_fence: 10182 10183'``fence``' Instruction 10184^^^^^^^^^^^^^^^^^^^^^^^ 10185 10186Syntax: 10187""""""" 10188 10189:: 10190 10191 fence [syncscope("<target-scope>")] <ordering> ; yields void 10192 10193Overview: 10194""""""""" 10195 10196The '``fence``' instruction is used to introduce happens-before edges 10197between operations. 10198 10199Arguments: 10200"""""""""" 10201 10202'``fence``' instructions take an :ref:`ordering <ordering>` argument which 10203defines what *synchronizes-with* edges they add. They can only be given 10204``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings. 10205 10206Semantics: 10207"""""""""" 10208 10209A fence A which has (at least) ``release`` ordering semantics 10210*synchronizes with* a fence B with (at least) ``acquire`` ordering 10211semantics if and only if there exist atomic operations X and Y, both 10212operating on some atomic object M, such that A is sequenced before X, X 10213modifies M (either directly or through some side effect of a sequence 10214headed by X), Y is sequenced before B, and Y observes M. This provides a 10215*happens-before* dependency between A and B. Rather than an explicit 10216``fence``, one (but not both) of the atomic operations X or Y might 10217provide a ``release`` or ``acquire`` (resp.) ordering constraint and 10218still *synchronize-with* the explicit ``fence`` and establish the 10219*happens-before* edge. 10220 10221A ``fence`` which has ``seq_cst`` ordering, in addition to having both 10222``acquire`` and ``release`` semantics specified above, participates in 10223the global program order of other ``seq_cst`` operations and/or fences. 10224 10225A ``fence`` instruction can also take an optional 10226":ref:`syncscope <syncscope>`" argument. 10227 10228Example: 10229"""""""" 10230 10231.. code-block:: text 10232 10233 fence acquire ; yields void 10234 fence syncscope("singlethread") seq_cst ; yields void 10235 fence syncscope("agent") seq_cst ; yields void 10236 10237.. _i_cmpxchg: 10238 10239'``cmpxchg``' Instruction 10240^^^^^^^^^^^^^^^^^^^^^^^^^ 10241 10242Syntax: 10243""""""" 10244 10245:: 10246 10247 cmpxchg [weak] [volatile] ptr <pointer>, <ty> <cmp>, <ty> <new> [syncscope("<target-scope>")] <success ordering> <failure ordering>[, align <alignment>] ; yields { ty, i1 } 10248 10249Overview: 10250""""""""" 10251 10252The '``cmpxchg``' instruction is used to atomically modify memory. It 10253loads a value in memory and compares it to a given value. If they are 10254equal, it tries to store a new value into the memory. 10255 10256Arguments: 10257"""""""""" 10258 10259There are three arguments to the '``cmpxchg``' instruction: an address 10260to operate on, a value to compare to the value currently be at that 10261address, and a new value to place at that address if the compared values 10262are equal. The type of '<cmp>' must be an integer or pointer type whose 10263bit width is a power of two greater than or equal to eight and less 10264than or equal to a target-specific size limit. '<cmp>' and '<new>' must 10265have the same type, and the type of '<pointer>' must be a pointer to 10266that type. If the ``cmpxchg`` is marked as ``volatile``, then the 10267optimizer is not allowed to modify the number or order of execution of 10268this ``cmpxchg`` with other :ref:`volatile operations <volatile>`. 10269 10270The success and failure :ref:`ordering <ordering>` arguments specify how this 10271``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters 10272must be at least ``monotonic``, the failure ordering cannot be either 10273``release`` or ``acq_rel``. 10274 10275A ``cmpxchg`` instruction can also take an optional 10276":ref:`syncscope <syncscope>`" argument. 10277 10278The instruction can take an optional ``align`` attribute. 10279The alignment must be a power of two greater or equal to the size of the 10280`<value>` type. If unspecified, the alignment is assumed to be equal to the 10281size of the '<value>' type. Note that this default alignment assumption is 10282different from the alignment used for the load/store instructions when align 10283isn't specified. 10284 10285The pointer passed into cmpxchg must have alignment greater than or 10286equal to the size in memory of the operand. 10287 10288Semantics: 10289"""""""""" 10290 10291The contents of memory at the location specified by the '``<pointer>``' operand 10292is read and compared to '``<cmp>``'; if the values are equal, '``<new>``' is 10293written to the location. The original value at the location is returned, 10294together with a flag indicating success (true) or failure (false). 10295 10296If the cmpxchg operation is marked as ``weak`` then a spurious failure is 10297permitted: the operation may not write ``<new>`` even if the comparison 10298matched. 10299 10300If the cmpxchg operation is strong (the default), the i1 value is 1 if and only 10301if the value loaded equals ``cmp``. 10302 10303A successful ``cmpxchg`` is a read-modify-write instruction for the purpose of 10304identifying release sequences. A failed ``cmpxchg`` is equivalent to an atomic 10305load with an ordering parameter determined the second ordering parameter. 10306 10307Example: 10308"""""""" 10309 10310.. code-block:: llvm 10311 10312 entry: 10313 %orig = load atomic i32, ptr %ptr unordered, align 4 ; yields i32 10314 br label %loop 10315 10316 loop: 10317 %cmp = phi i32 [ %orig, %entry ], [%value_loaded, %loop] 10318 %squared = mul i32 %cmp, %cmp 10319 %val_success = cmpxchg ptr %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields { i32, i1 } 10320 %value_loaded = extractvalue { i32, i1 } %val_success, 0 10321 %success = extractvalue { i32, i1 } %val_success, 1 10322 br i1 %success, label %done, label %loop 10323 10324 done: 10325 ... 10326 10327.. _i_atomicrmw: 10328 10329'``atomicrmw``' Instruction 10330^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10331 10332Syntax: 10333""""""" 10334 10335:: 10336 10337 atomicrmw [volatile] <operation> ptr <pointer>, <ty> <value> [syncscope("<target-scope>")] <ordering>[, align <alignment>] ; yields ty 10338 10339Overview: 10340""""""""" 10341 10342The '``atomicrmw``' instruction is used to atomically modify memory. 10343 10344Arguments: 10345"""""""""" 10346 10347There are three arguments to the '``atomicrmw``' instruction: an 10348operation to apply, an address whose value to modify, an argument to the 10349operation. The operation must be one of the following keywords: 10350 10351- xchg 10352- add 10353- sub 10354- and 10355- nand 10356- or 10357- xor 10358- max 10359- min 10360- umax 10361- umin 10362- fadd 10363- fsub 10364- fmax 10365- fmin 10366 10367For most of these operations, the type of '<value>' must be an integer 10368type whose bit width is a power of two greater than or equal to eight 10369and less than or equal to a target-specific size limit. For xchg, this 10370may also be a floating point or a pointer type with the same size constraints 10371as integers. For fadd/fsub/fmax/fmin, this must be a floating point type. The 10372type of the '``<pointer>``' operand must be a pointer to that type. If 10373the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not 10374allowed to modify the number or order of execution of this 10375``atomicrmw`` with other :ref:`volatile operations <volatile>`. 10376 10377The instruction can take an optional ``align`` attribute. 10378The alignment must be a power of two greater or equal to the size of the 10379`<value>` type. If unspecified, the alignment is assumed to be equal to the 10380size of the '<value>' type. Note that this default alignment assumption is 10381different from the alignment used for the load/store instructions when align 10382isn't specified. 10383 10384A ``atomicrmw`` instruction can also take an optional 10385":ref:`syncscope <syncscope>`" argument. 10386 10387Semantics: 10388"""""""""" 10389 10390The contents of memory at the location specified by the '``<pointer>``' 10391operand are atomically read, modified, and written back. The original 10392value at the location is returned. The modification is specified by the 10393operation argument: 10394 10395- xchg: ``*ptr = val`` 10396- add: ``*ptr = *ptr + val`` 10397- sub: ``*ptr = *ptr - val`` 10398- and: ``*ptr = *ptr & val`` 10399- nand: ``*ptr = ~(*ptr & val)`` 10400- or: ``*ptr = *ptr | val`` 10401- xor: ``*ptr = *ptr ^ val`` 10402- max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison) 10403- min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison) 10404- umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned comparison) 10405- umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned comparison) 10406- fadd: ``*ptr = *ptr + val`` (using floating point arithmetic) 10407- fsub: ``*ptr = *ptr - val`` (using floating point arithmetic) 10408- fmax: ``*ptr = maxnum(*ptr, val)`` (match the `llvm.maxnum.*`` intrinsic) 10409- fmin: ``*ptr = minnum(*ptr, val)`` (match the `llvm.minnum.*`` intrinsic) 10410 10411Example: 10412"""""""" 10413 10414.. code-block:: llvm 10415 10416 %old = atomicrmw add ptr %ptr, i32 1 acquire ; yields i32 10417 10418.. _i_getelementptr: 10419 10420'``getelementptr``' Instruction 10421^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10422 10423Syntax: 10424""""""" 10425 10426:: 10427 10428 <result> = getelementptr <ty>, ptr <ptrval>{, [inrange] <ty> <idx>}* 10429 <result> = getelementptr inbounds ptr <ptrval>{, [inrange] <ty> <idx>}* 10430 <result> = getelementptr <ty>, <N x ptr> <ptrval>, [inrange] <vector index type> <idx> 10431 10432Overview: 10433""""""""" 10434 10435The '``getelementptr``' instruction is used to get the address of a 10436subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs 10437address calculation only and does not access memory. The instruction can also 10438be used to calculate a vector of such addresses. 10439 10440Arguments: 10441"""""""""" 10442 10443The first argument is always a type used as the basis for the calculations. 10444The second argument is always a pointer or a vector of pointers, and is the 10445base address to start from. The remaining arguments are indices 10446that indicate which of the elements of the aggregate object are indexed. 10447The interpretation of each index is dependent on the type being indexed 10448into. The first index always indexes the pointer value given as the 10449second argument, the second index indexes a value of the type pointed to 10450(not necessarily the value directly pointed to, since the first index 10451can be non-zero), etc. The first type indexed into must be a pointer 10452value, subsequent types can be arrays, vectors, and structs. Note that 10453subsequent types being indexed into can never be pointers, since that 10454would require loading the pointer before continuing calculation. 10455 10456The type of each index argument depends on the type it is indexing into. 10457When indexing into a (optionally packed) structure, only ``i32`` integer 10458**constants** are allowed (when using a vector of indices they must all 10459be the **same** ``i32`` integer constant). When indexing into an array, 10460pointer or vector, integers of any width are allowed, and they are not 10461required to be constant. These integers are treated as signed values 10462where relevant. 10463 10464For example, let's consider a C code fragment and how it gets compiled 10465to LLVM: 10466 10467.. code-block:: c 10468 10469 struct RT { 10470 char A; 10471 int B[10][20]; 10472 char C; 10473 }; 10474 struct ST { 10475 int X; 10476 double Y; 10477 struct RT Z; 10478 }; 10479 10480 int *foo(struct ST *s) { 10481 return &s[1].Z.B[5][13]; 10482 } 10483 10484The LLVM code generated by Clang is: 10485 10486.. code-block:: llvm 10487 10488 %struct.RT = type { i8, [10 x [20 x i32]], i8 } 10489 %struct.ST = type { i32, double, %struct.RT } 10490 10491 define ptr @foo(ptr %s) nounwind uwtable readnone optsize ssp { 10492 entry: 10493 %arrayidx = getelementptr inbounds %struct.ST, ptr %s, i64 1, i32 2, i32 1, i64 5, i64 13 10494 ret ptr %arrayidx 10495 } 10496 10497Semantics: 10498"""""""""" 10499 10500In the example above, the first index is indexing into the 10501'``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``' 10502= '``{ i32, double, %struct.RT }``' type, a structure. The second index 10503indexes into the third element of the structure, yielding a 10504'``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another 10505structure. The third index indexes into the second element of the 10506structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two 10507dimensions of the array are subscripted into, yielding an '``i32``' 10508type. The '``getelementptr``' instruction returns a pointer to this 10509element. 10510 10511Note that it is perfectly legal to index partially through a structure, 10512returning a pointer to an inner element. Because of this, the LLVM code 10513for the given testcase is equivalent to: 10514 10515.. code-block:: llvm 10516 10517 define ptr @foo(ptr %s) { 10518 %t1 = getelementptr %struct.ST, ptr %s, i32 1 10519 %t2 = getelementptr %struct.ST, ptr %t1, i32 0, i32 2 10520 %t3 = getelementptr %struct.RT, ptr %t2, i32 0, i32 1 10521 %t4 = getelementptr [10 x [20 x i32]], ptr %t3, i32 0, i32 5 10522 %t5 = getelementptr [20 x i32], ptr %t4, i32 0, i32 13 10523 ret ptr %t5 10524 } 10525 10526If the ``inbounds`` keyword is present, the result value of the 10527``getelementptr`` is a :ref:`poison value <poisonvalues>` if one of the 10528following rules is violated: 10529 10530* The base pointer has an *in bounds* address of an allocated object, which 10531 means that it points into an allocated object, or to its end. The only 10532 *in bounds* address for a null pointer in the default address-space is the 10533 null pointer itself. 10534* If the type of an index is larger than the pointer index type, the 10535 truncation to the pointer index type preserves the signed value. 10536* The multiplication of an index by the type size does not wrap the pointer 10537 index type in a signed sense (``nsw``). 10538* The successive addition of offsets (without adding the base address) does 10539 not wrap the pointer index type in a signed sense (``nsw``). 10540* The successive addition of the current address, interpreted as an unsigned 10541 number, and an offset, interpreted as a signed number, does not wrap the 10542 unsigned address space and remains *in bounds* of the allocated object. 10543 As a corollary, if the added offset is non-negative, the addition does not 10544 wrap in an unsigned sense (``nuw``). 10545* In cases where the base is a vector of pointers, the ``inbounds`` keyword 10546 applies to each of the computations element-wise. 10547 10548These rules are based on the assumption that no allocated object may cross 10549the unsigned address space boundary, and no allocated object may be larger 10550than half the pointer index type space. 10551 10552If the ``inbounds`` keyword is not present, the offsets are added to the 10553base address with silently-wrapping two's complement arithmetic. If the 10554offsets have a different width from the pointer, they are sign-extended 10555or truncated to the width of the pointer. The result value of the 10556``getelementptr`` may be outside the object pointed to by the base 10557pointer. The result value may not necessarily be used to access memory 10558though, even if it happens to point into allocated storage. See the 10559:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more 10560information. 10561 10562If the ``inrange`` keyword is present before any index, loading from or 10563storing to any pointer derived from the ``getelementptr`` has undefined 10564behavior if the load or store would access memory outside of the bounds of 10565the element selected by the index marked as ``inrange``. The result of a 10566pointer comparison or ``ptrtoint`` (including ``ptrtoint``-like operations 10567involving memory) involving a pointer derived from a ``getelementptr`` with 10568the ``inrange`` keyword is undefined, with the exception of comparisons 10569in the case where both operands are in the range of the element selected 10570by the ``inrange`` keyword, inclusive of the address one past the end of 10571that element. Note that the ``inrange`` keyword is currently only allowed 10572in constant ``getelementptr`` expressions. 10573 10574The getelementptr instruction is often confusing. For some more insight 10575into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`. 10576 10577Example: 10578"""""""" 10579 10580.. code-block:: llvm 10581 10582 %aptr = getelementptr {i32, [12 x i8]}, ptr %saptr, i64 0, i32 1 10583 %vptr = getelementptr {i32, <2 x i8>}, ptr %svptr, i64 0, i32 1, i32 1 10584 %eptr = getelementptr [12 x i8], ptr %aptr, i64 0, i32 1 10585 %iptr = getelementptr [10 x i32], ptr @arr, i16 0, i16 0 10586 10587Vector of pointers: 10588""""""""""""""""""" 10589 10590The ``getelementptr`` returns a vector of pointers, instead of a single address, 10591when one or more of its arguments is a vector. In such cases, all vector 10592arguments should have the same number of elements, and every scalar argument 10593will be effectively broadcast into a vector during address calculation. 10594 10595.. code-block:: llvm 10596 10597 ; All arguments are vectors: 10598 ; A[i] = ptrs[i] + offsets[i]*sizeof(i8) 10599 %A = getelementptr i8, <4 x i8*> %ptrs, <4 x i64> %offsets 10600 10601 ; Add the same scalar offset to each pointer of a vector: 10602 ; A[i] = ptrs[i] + offset*sizeof(i8) 10603 %A = getelementptr i8, <4 x ptr> %ptrs, i64 %offset 10604 10605 ; Add distinct offsets to the same pointer: 10606 ; A[i] = ptr + offsets[i]*sizeof(i8) 10607 %A = getelementptr i8, ptr %ptr, <4 x i64> %offsets 10608 10609 ; In all cases described above the type of the result is <4 x ptr> 10610 10611The two following instructions are equivalent: 10612 10613.. code-block:: llvm 10614 10615 getelementptr %struct.ST, <4 x ptr> %s, <4 x i64> %ind1, 10616 <4 x i32> <i32 2, i32 2, i32 2, i32 2>, 10617 <4 x i32> <i32 1, i32 1, i32 1, i32 1>, 10618 <4 x i32> %ind4, 10619 <4 x i64> <i64 13, i64 13, i64 13, i64 13> 10620 10621 getelementptr %struct.ST, <4 x ptr> %s, <4 x i64> %ind1, 10622 i32 2, i32 1, <4 x i32> %ind4, i64 13 10623 10624Let's look at the C code, where the vector version of ``getelementptr`` 10625makes sense: 10626 10627.. code-block:: c 10628 10629 // Let's assume that we vectorize the following loop: 10630 double *A, *B; int *C; 10631 for (int i = 0; i < size; ++i) { 10632 A[i] = B[C[i]]; 10633 } 10634 10635.. code-block:: llvm 10636 10637 ; get pointers for 8 elements from array B 10638 %ptrs = getelementptr double, ptr %B, <8 x i32> %C 10639 ; load 8 elements from array B into A 10640 %A = call <8 x double> @llvm.masked.gather.v8f64.v8p0f64(<8 x ptr> %ptrs, 10641 i32 8, <8 x i1> %mask, <8 x double> %passthru) 10642 10643Conversion Operations 10644--------------------- 10645 10646The instructions in this category are the conversion instructions 10647(casting) which all take a single operand and a type. They perform 10648various bit conversions on the operand. 10649 10650.. _i_trunc: 10651 10652'``trunc .. to``' Instruction 10653^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10654 10655Syntax: 10656""""""" 10657 10658:: 10659 10660 <result> = trunc <ty> <value> to <ty2> ; yields ty2 10661 10662Overview: 10663""""""""" 10664 10665The '``trunc``' instruction truncates its operand to the type ``ty2``. 10666 10667Arguments: 10668"""""""""" 10669 10670The '``trunc``' instruction takes a value to trunc, and a type to trunc 10671it to. Both types must be of :ref:`integer <t_integer>` types, or vectors 10672of the same number of integers. The bit size of the ``value`` must be 10673larger than the bit size of the destination type, ``ty2``. Equal sized 10674types are not allowed. 10675 10676Semantics: 10677"""""""""" 10678 10679The '``trunc``' instruction truncates the high order bits in ``value`` 10680and converts the remaining bits to ``ty2``. Since the source size must 10681be larger than the destination size, ``trunc`` cannot be a *no-op cast*. 10682It will always truncate bits. 10683 10684Example: 10685"""""""" 10686 10687.. code-block:: llvm 10688 10689 %X = trunc i32 257 to i8 ; yields i8:1 10690 %Y = trunc i32 123 to i1 ; yields i1:true 10691 %Z = trunc i32 122 to i1 ; yields i1:false 10692 %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7> 10693 10694.. _i_zext: 10695 10696'``zext .. to``' Instruction 10697^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10698 10699Syntax: 10700""""""" 10701 10702:: 10703 10704 <result> = zext <ty> <value> to <ty2> ; yields ty2 10705 10706Overview: 10707""""""""" 10708 10709The '``zext``' instruction zero extends its operand to type ``ty2``. 10710 10711Arguments: 10712"""""""""" 10713 10714The '``zext``' instruction takes a value to cast, and a type to cast it 10715to. Both types must be of :ref:`integer <t_integer>` types, or vectors of 10716the same number of integers. The bit size of the ``value`` must be 10717smaller than the bit size of the destination type, ``ty2``. 10718 10719Semantics: 10720"""""""""" 10721 10722The ``zext`` fills the high order bits of the ``value`` with zero bits 10723until it reaches the size of the destination type, ``ty2``. 10724 10725When zero extending from i1, the result will always be either 0 or 1. 10726 10727Example: 10728"""""""" 10729 10730.. code-block:: llvm 10731 10732 %X = zext i32 257 to i64 ; yields i64:257 10733 %Y = zext i1 true to i32 ; yields i32:1 10734 %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> 10735 10736.. _i_sext: 10737 10738'``sext .. to``' Instruction 10739^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10740 10741Syntax: 10742""""""" 10743 10744:: 10745 10746 <result> = sext <ty> <value> to <ty2> ; yields ty2 10747 10748Overview: 10749""""""""" 10750 10751The '``sext``' sign extends ``value`` to the type ``ty2``. 10752 10753Arguments: 10754"""""""""" 10755 10756The '``sext``' instruction takes a value to cast, and a type to cast it 10757to. Both types must be of :ref:`integer <t_integer>` types, or vectors of 10758the same number of integers. The bit size of the ``value`` must be 10759smaller than the bit size of the destination type, ``ty2``. 10760 10761Semantics: 10762"""""""""" 10763 10764The '``sext``' instruction performs a sign extension by copying the sign 10765bit (highest order bit) of the ``value`` until it reaches the bit size 10766of the type ``ty2``. 10767 10768When sign extending from i1, the extension always results in -1 or 0. 10769 10770Example: 10771"""""""" 10772 10773.. code-block:: llvm 10774 10775 %X = sext i8 -1 to i16 ; yields i16 :65535 10776 %Y = sext i1 true to i32 ; yields i32:-1 10777 %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> 10778 10779'``fptrunc .. to``' Instruction 10780^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10781 10782Syntax: 10783""""""" 10784 10785:: 10786 10787 <result> = fptrunc <ty> <value> to <ty2> ; yields ty2 10788 10789Overview: 10790""""""""" 10791 10792The '``fptrunc``' instruction truncates ``value`` to type ``ty2``. 10793 10794Arguments: 10795"""""""""" 10796 10797The '``fptrunc``' instruction takes a :ref:`floating-point <t_floating>` 10798value to cast and a :ref:`floating-point <t_floating>` type to cast it to. 10799The size of ``value`` must be larger than the size of ``ty2``. This 10800implies that ``fptrunc`` cannot be used to make a *no-op cast*. 10801 10802Semantics: 10803"""""""""" 10804 10805The '``fptrunc``' instruction casts a ``value`` from a larger 10806:ref:`floating-point <t_floating>` type to a smaller :ref:`floating-point 10807<t_floating>` type. 10808This instruction is assumed to execute in the default :ref:`floating-point 10809environment <floatenv>`. 10810 10811Example: 10812"""""""" 10813 10814.. code-block:: llvm 10815 10816 %X = fptrunc double 16777217.0 to float ; yields float:16777216.0 10817 %Y = fptrunc double 1.0E+300 to half ; yields half:+infinity 10818 10819'``fpext .. to``' Instruction 10820^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10821 10822Syntax: 10823""""""" 10824 10825:: 10826 10827 <result> = fpext <ty> <value> to <ty2> ; yields ty2 10828 10829Overview: 10830""""""""" 10831 10832The '``fpext``' extends a floating-point ``value`` to a larger floating-point 10833value. 10834 10835Arguments: 10836"""""""""" 10837 10838The '``fpext``' instruction takes a :ref:`floating-point <t_floating>` 10839``value`` to cast, and a :ref:`floating-point <t_floating>` type to cast it 10840to. The source type must be smaller than the destination type. 10841 10842Semantics: 10843"""""""""" 10844 10845The '``fpext``' instruction extends the ``value`` from a smaller 10846:ref:`floating-point <t_floating>` type to a larger :ref:`floating-point 10847<t_floating>` type. The ``fpext`` cannot be used to make a 10848*no-op cast* because it always changes bits. Use ``bitcast`` to make a 10849*no-op cast* for a floating-point cast. 10850 10851Example: 10852"""""""" 10853 10854.. code-block:: llvm 10855 10856 %X = fpext float 3.125 to double ; yields double:3.125000e+00 10857 %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000 10858 10859'``fptoui .. to``' Instruction 10860^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10861 10862Syntax: 10863""""""" 10864 10865:: 10866 10867 <result> = fptoui <ty> <value> to <ty2> ; yields ty2 10868 10869Overview: 10870""""""""" 10871 10872The '``fptoui``' converts a floating-point ``value`` to its unsigned 10873integer equivalent of type ``ty2``. 10874 10875Arguments: 10876"""""""""" 10877 10878The '``fptoui``' instruction takes a value to cast, which must be a 10879scalar or vector :ref:`floating-point <t_floating>` value, and a type to 10880cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If 10881``ty`` is a vector floating-point type, ``ty2`` must be a vector integer 10882type with the same number of elements as ``ty`` 10883 10884Semantics: 10885"""""""""" 10886 10887The '``fptoui``' instruction converts its :ref:`floating-point 10888<t_floating>` operand into the nearest (rounding towards zero) 10889unsigned integer value. If the value cannot fit in ``ty2``, the result 10890is a :ref:`poison value <poisonvalues>`. 10891 10892Example: 10893"""""""" 10894 10895.. code-block:: llvm 10896 10897 %X = fptoui double 123.0 to i32 ; yields i32:123 10898 %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1 10899 %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1 10900 10901'``fptosi .. to``' Instruction 10902^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10903 10904Syntax: 10905""""""" 10906 10907:: 10908 10909 <result> = fptosi <ty> <value> to <ty2> ; yields ty2 10910 10911Overview: 10912""""""""" 10913 10914The '``fptosi``' instruction converts :ref:`floating-point <t_floating>` 10915``value`` to type ``ty2``. 10916 10917Arguments: 10918"""""""""" 10919 10920The '``fptosi``' instruction takes a value to cast, which must be a 10921scalar or vector :ref:`floating-point <t_floating>` value, and a type to 10922cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If 10923``ty`` is a vector floating-point type, ``ty2`` must be a vector integer 10924type with the same number of elements as ``ty`` 10925 10926Semantics: 10927"""""""""" 10928 10929The '``fptosi``' instruction converts its :ref:`floating-point 10930<t_floating>` operand into the nearest (rounding towards zero) 10931signed integer value. If the value cannot fit in ``ty2``, the result 10932is a :ref:`poison value <poisonvalues>`. 10933 10934Example: 10935"""""""" 10936 10937.. code-block:: llvm 10938 10939 %X = fptosi double -123.0 to i32 ; yields i32:-123 10940 %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1 10941 %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1 10942 10943'``uitofp .. to``' Instruction 10944^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10945 10946Syntax: 10947""""""" 10948 10949:: 10950 10951 <result> = uitofp <ty> <value> to <ty2> ; yields ty2 10952 10953Overview: 10954""""""""" 10955 10956The '``uitofp``' instruction regards ``value`` as an unsigned integer 10957and converts that value to the ``ty2`` type. 10958 10959Arguments: 10960"""""""""" 10961 10962The '``uitofp``' instruction takes a value to cast, which must be a 10963scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to 10964``ty2``, which must be an :ref:`floating-point <t_floating>` type. If 10965``ty`` is a vector integer type, ``ty2`` must be a vector floating-point 10966type with the same number of elements as ``ty`` 10967 10968Semantics: 10969"""""""""" 10970 10971The '``uitofp``' instruction interprets its operand as an unsigned 10972integer quantity and converts it to the corresponding floating-point 10973value. If the value cannot be exactly represented, it is rounded using 10974the default rounding mode. 10975 10976 10977Example: 10978"""""""" 10979 10980.. code-block:: llvm 10981 10982 %X = uitofp i32 257 to float ; yields float:257.0 10983 %Y = uitofp i8 -1 to double ; yields double:255.0 10984 10985'``sitofp .. to``' Instruction 10986^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 10987 10988Syntax: 10989""""""" 10990 10991:: 10992 10993 <result> = sitofp <ty> <value> to <ty2> ; yields ty2 10994 10995Overview: 10996""""""""" 10997 10998The '``sitofp``' instruction regards ``value`` as a signed integer and 10999converts that value to the ``ty2`` type. 11000 11001Arguments: 11002"""""""""" 11003 11004The '``sitofp``' instruction takes a value to cast, which must be a 11005scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to 11006``ty2``, which must be an :ref:`floating-point <t_floating>` type. If 11007``ty`` is a vector integer type, ``ty2`` must be a vector floating-point 11008type with the same number of elements as ``ty`` 11009 11010Semantics: 11011"""""""""" 11012 11013The '``sitofp``' instruction interprets its operand as a signed integer 11014quantity and converts it to the corresponding floating-point value. If the 11015value cannot be exactly represented, it is rounded using the default rounding 11016mode. 11017 11018Example: 11019"""""""" 11020 11021.. code-block:: llvm 11022 11023 %X = sitofp i32 257 to float ; yields float:257.0 11024 %Y = sitofp i8 -1 to double ; yields double:-1.0 11025 11026.. _i_ptrtoint: 11027 11028'``ptrtoint .. to``' Instruction 11029^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11030 11031Syntax: 11032""""""" 11033 11034:: 11035 11036 <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2 11037 11038Overview: 11039""""""""" 11040 11041The '``ptrtoint``' instruction converts the pointer or a vector of 11042pointers ``value`` to the integer (or vector of integers) type ``ty2``. 11043 11044Arguments: 11045"""""""""" 11046 11047The '``ptrtoint``' instruction takes a ``value`` to cast, which must be 11048a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a 11049type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or 11050a vector of integers type. 11051 11052Semantics: 11053"""""""""" 11054 11055The '``ptrtoint``' instruction converts ``value`` to integer type 11056``ty2`` by interpreting the pointer value as an integer and either 11057truncating or zero extending that value to the size of the integer type. 11058If ``value`` is smaller than ``ty2`` then a zero extension is done. If 11059``value`` is larger than ``ty2`` then a truncation is done. If they are 11060the same size, then nothing is done (*no-op cast*) other than a type 11061change. 11062 11063Example: 11064"""""""" 11065 11066.. code-block:: llvm 11067 11068 %X = ptrtoint ptr %P to i8 ; yields truncation on 32-bit architecture 11069 %Y = ptrtoint ptr %P to i64 ; yields zero extension on 32-bit architecture 11070 %Z = ptrtoint <4 x ptr> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture 11071 11072.. _i_inttoptr: 11073 11074'``inttoptr .. to``' Instruction 11075^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11076 11077Syntax: 11078""""""" 11079 11080:: 11081 11082 <result> = inttoptr <ty> <value> to <ty2>[, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>] ; yields ty2 11083 11084Overview: 11085""""""""" 11086 11087The '``inttoptr``' instruction converts an integer ``value`` to a 11088pointer type, ``ty2``. 11089 11090Arguments: 11091"""""""""" 11092 11093The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to 11094cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>` 11095type. 11096 11097The optional ``!dereferenceable`` metadata must reference a single metadata 11098name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64`` 11099entry. 11100See ``dereferenceable`` metadata. 11101 11102The optional ``!dereferenceable_or_null`` metadata must reference a single 11103metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one 11104``i64`` entry. 11105See ``dereferenceable_or_null`` metadata. 11106 11107Semantics: 11108"""""""""" 11109 11110The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by 11111applying either a zero extension or a truncation depending on the size 11112of the integer ``value``. If ``value`` is larger than the size of a 11113pointer then a truncation is done. If ``value`` is smaller than the size 11114of a pointer then a zero extension is done. If they are the same size, 11115nothing is done (*no-op cast*). 11116 11117Example: 11118"""""""" 11119 11120.. code-block:: llvm 11121 11122 %X = inttoptr i32 255 to ptr ; yields zero extension on 64-bit architecture 11123 %Y = inttoptr i32 255 to ptr ; yields no-op on 32-bit architecture 11124 %Z = inttoptr i64 0 to ptr ; yields truncation on 32-bit architecture 11125 %Z = inttoptr <4 x i32> %G to <4 x ptr>; yields truncation of vector G to four pointers 11126 11127.. _i_bitcast: 11128 11129'``bitcast .. to``' Instruction 11130^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11131 11132Syntax: 11133""""""" 11134 11135:: 11136 11137 <result> = bitcast <ty> <value> to <ty2> ; yields ty2 11138 11139Overview: 11140""""""""" 11141 11142The '``bitcast``' instruction converts ``value`` to type ``ty2`` without 11143changing any bits. 11144 11145Arguments: 11146"""""""""" 11147 11148The '``bitcast``' instruction takes a value to cast, which must be a 11149non-aggregate first class value, and a type to cast it to, which must 11150also be a non-aggregate :ref:`first class <t_firstclass>` type. The 11151bit sizes of ``value`` and the destination type, ``ty2``, must be 11152identical. If the source type is a pointer, the destination type must 11153also be a pointer of the same size. This instruction supports bitwise 11154conversion of vectors to integers and to vectors of other types (as 11155long as they have the same size). 11156 11157Semantics: 11158"""""""""" 11159 11160The '``bitcast``' instruction converts ``value`` to type ``ty2``. It 11161is always a *no-op cast* because no bits change with this 11162conversion. The conversion is done as if the ``value`` had been stored 11163to memory and read back as type ``ty2``. Pointer (or vector of 11164pointers) types may only be converted to other pointer (or vector of 11165pointers) types with the same address space through this instruction. 11166To convert pointers to other types, use the :ref:`inttoptr <i_inttoptr>` 11167or :ref:`ptrtoint <i_ptrtoint>` instructions first. 11168 11169There is a caveat for bitcasts involving vector types in relation to 11170endianess. For example ``bitcast <2 x i8> <value> to i16`` puts element zero 11171of the vector in the least significant bits of the i16 for little-endian while 11172element zero ends up in the most significant bits for big-endian. 11173 11174Example: 11175"""""""" 11176 11177.. code-block:: text 11178 11179 %X = bitcast i8 255 to i8 ; yields i8 :-1 11180 %Y = bitcast i32* %x to i16* ; yields i16*:%x 11181 %Z = bitcast <2 x i32> %V to i64; ; yields i64: %V (depends on endianess) 11182 %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*> 11183 11184.. _i_addrspacecast: 11185 11186'``addrspacecast .. to``' Instruction 11187^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11188 11189Syntax: 11190""""""" 11191 11192:: 11193 11194 <result> = addrspacecast <pty> <ptrval> to <pty2> ; yields pty2 11195 11196Overview: 11197""""""""" 11198 11199The '``addrspacecast``' instruction converts ``ptrval`` from ``pty`` in 11200address space ``n`` to type ``pty2`` in address space ``m``. 11201 11202Arguments: 11203"""""""""" 11204 11205The '``addrspacecast``' instruction takes a pointer or vector of pointer value 11206to cast and a pointer type to cast it to, which must have a different 11207address space. 11208 11209Semantics: 11210"""""""""" 11211 11212The '``addrspacecast``' instruction converts the pointer value 11213``ptrval`` to type ``pty2``. It can be a *no-op cast* or a complex 11214value modification, depending on the target and the address space 11215pair. Pointer conversions within the same address space must be 11216performed with the ``bitcast`` instruction. Note that if the address space 11217conversion is legal then both result and operand refer to the same memory 11218location. 11219 11220Example: 11221"""""""" 11222 11223.. code-block:: llvm 11224 11225 %X = addrspacecast ptr %x to ptr addrspace(1) 11226 %Y = addrspacecast ptr addrspace(1) %y to ptr addrspace(2) 11227 %Z = addrspacecast <4 x ptr> %z to <4 x ptr addrspace(3)> 11228 11229.. _otherops: 11230 11231Other Operations 11232---------------- 11233 11234The instructions in this category are the "miscellaneous" instructions, 11235which defy better classification. 11236 11237.. _i_icmp: 11238 11239'``icmp``' Instruction 11240^^^^^^^^^^^^^^^^^^^^^^ 11241 11242Syntax: 11243""""""" 11244 11245:: 11246 11247 <result> = icmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result 11248 11249Overview: 11250""""""""" 11251 11252The '``icmp``' instruction returns a boolean value or a vector of 11253boolean values based on comparison of its two integer, integer vector, 11254pointer, or pointer vector operands. 11255 11256Arguments: 11257"""""""""" 11258 11259The '``icmp``' instruction takes three operands. The first operand is 11260the condition code indicating the kind of comparison to perform. It is 11261not a value, just a keyword. The possible condition codes are: 11262 11263.. _icmp_md_cc: 11264 11265#. ``eq``: equal 11266#. ``ne``: not equal 11267#. ``ugt``: unsigned greater than 11268#. ``uge``: unsigned greater or equal 11269#. ``ult``: unsigned less than 11270#. ``ule``: unsigned less or equal 11271#. ``sgt``: signed greater than 11272#. ``sge``: signed greater or equal 11273#. ``slt``: signed less than 11274#. ``sle``: signed less or equal 11275 11276The remaining two arguments must be :ref:`integer <t_integer>` or 11277:ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They 11278must also be identical types. 11279 11280Semantics: 11281"""""""""" 11282 11283The '``icmp``' compares ``op1`` and ``op2`` according to the condition 11284code given as ``cond``. The comparison performed always yields either an 11285:ref:`i1 <t_integer>` or vector of ``i1`` result, as follows: 11286 11287.. _icmp_md_cc_sem: 11288 11289#. ``eq``: yields ``true`` if the operands are equal, ``false`` 11290 otherwise. No sign interpretation is necessary or performed. 11291#. ``ne``: yields ``true`` if the operands are unequal, ``false`` 11292 otherwise. No sign interpretation is necessary or performed. 11293#. ``ugt``: interprets the operands as unsigned values and yields 11294 ``true`` if ``op1`` is greater than ``op2``. 11295#. ``uge``: interprets the operands as unsigned values and yields 11296 ``true`` if ``op1`` is greater than or equal to ``op2``. 11297#. ``ult``: interprets the operands as unsigned values and yields 11298 ``true`` if ``op1`` is less than ``op2``. 11299#. ``ule``: interprets the operands as unsigned values and yields 11300 ``true`` if ``op1`` is less than or equal to ``op2``. 11301#. ``sgt``: interprets the operands as signed values and yields ``true`` 11302 if ``op1`` is greater than ``op2``. 11303#. ``sge``: interprets the operands as signed values and yields ``true`` 11304 if ``op1`` is greater than or equal to ``op2``. 11305#. ``slt``: interprets the operands as signed values and yields ``true`` 11306 if ``op1`` is less than ``op2``. 11307#. ``sle``: interprets the operands as signed values and yields ``true`` 11308 if ``op1`` is less than or equal to ``op2``. 11309 11310If the operands are :ref:`pointer <t_pointer>` typed, the pointer values 11311are compared as if they were integers. 11312 11313If the operands are integer vectors, then they are compared element by 11314element. The result is an ``i1`` vector with the same number of elements 11315as the values being compared. Otherwise, the result is an ``i1``. 11316 11317Example: 11318"""""""" 11319 11320.. code-block:: text 11321 11322 <result> = icmp eq i32 4, 5 ; yields: result=false 11323 <result> = icmp ne ptr %X, %X ; yields: result=false 11324 <result> = icmp ult i16 4, 5 ; yields: result=true 11325 <result> = icmp sgt i16 4, 5 ; yields: result=false 11326 <result> = icmp ule i16 -4, 5 ; yields: result=false 11327 <result> = icmp sge i16 4, 5 ; yields: result=false 11328 11329.. _i_fcmp: 11330 11331'``fcmp``' Instruction 11332^^^^^^^^^^^^^^^^^^^^^^ 11333 11334Syntax: 11335""""""" 11336 11337:: 11338 11339 <result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result 11340 11341Overview: 11342""""""""" 11343 11344The '``fcmp``' instruction returns a boolean value or vector of boolean 11345values based on comparison of its operands. 11346 11347If the operands are floating-point scalars, then the result type is a 11348boolean (:ref:`i1 <t_integer>`). 11349 11350If the operands are floating-point vectors, then the result type is a 11351vector of boolean with the same number of elements as the operands being 11352compared. 11353 11354Arguments: 11355"""""""""" 11356 11357The '``fcmp``' instruction takes three operands. The first operand is 11358the condition code indicating the kind of comparison to perform. It is 11359not a value, just a keyword. The possible condition codes are: 11360 11361#. ``false``: no comparison, always returns false 11362#. ``oeq``: ordered and equal 11363#. ``ogt``: ordered and greater than 11364#. ``oge``: ordered and greater than or equal 11365#. ``olt``: ordered and less than 11366#. ``ole``: ordered and less than or equal 11367#. ``one``: ordered and not equal 11368#. ``ord``: ordered (no nans) 11369#. ``ueq``: unordered or equal 11370#. ``ugt``: unordered or greater than 11371#. ``uge``: unordered or greater than or equal 11372#. ``ult``: unordered or less than 11373#. ``ule``: unordered or less than or equal 11374#. ``une``: unordered or not equal 11375#. ``uno``: unordered (either nans) 11376#. ``true``: no comparison, always returns true 11377 11378*Ordered* means that neither operand is a QNAN while *unordered* means 11379that either operand may be a QNAN. 11380 11381Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating-point 11382<t_floating>` type or a :ref:`vector <t_vector>` of floating-point type. 11383They must have identical types. 11384 11385Semantics: 11386"""""""""" 11387 11388The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the 11389condition code given as ``cond``. If the operands are vectors, then the 11390vectors are compared element by element. Each comparison performed 11391always yields an :ref:`i1 <t_integer>` result, as follows: 11392 11393#. ``false``: always yields ``false``, regardless of operands. 11394#. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1`` 11395 is equal to ``op2``. 11396#. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1`` 11397 is greater than ``op2``. 11398#. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1`` 11399 is greater than or equal to ``op2``. 11400#. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1`` 11401 is less than ``op2``. 11402#. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1`` 11403 is less than or equal to ``op2``. 11404#. ``one``: yields ``true`` if both operands are not a QNAN and ``op1`` 11405 is not equal to ``op2``. 11406#. ``ord``: yields ``true`` if both operands are not a QNAN. 11407#. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is 11408 equal to ``op2``. 11409#. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is 11410 greater than ``op2``. 11411#. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is 11412 greater than or equal to ``op2``. 11413#. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is 11414 less than ``op2``. 11415#. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is 11416 less than or equal to ``op2``. 11417#. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is 11418 not equal to ``op2``. 11419#. ``uno``: yields ``true`` if either operand is a QNAN. 11420#. ``true``: always yields ``true``, regardless of operands. 11421 11422The ``fcmp`` instruction can also optionally take any number of 11423:ref:`fast-math flags <fastmath>`, which are optimization hints to enable 11424otherwise unsafe floating-point optimizations. 11425 11426Any set of fast-math flags are legal on an ``fcmp`` instruction, but the 11427only flags that have any effect on its semantics are those that allow 11428assumptions to be made about the values of input arguments; namely 11429``nnan``, ``ninf``, and ``reassoc``. See :ref:`fastmath` for more information. 11430 11431Example: 11432"""""""" 11433 11434.. code-block:: text 11435 11436 <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false 11437 <result> = fcmp one float 4.0, 5.0 ; yields: result=true 11438 <result> = fcmp olt float 4.0, 5.0 ; yields: result=true 11439 <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false 11440 11441.. _i_phi: 11442 11443'``phi``' Instruction 11444^^^^^^^^^^^^^^^^^^^^^ 11445 11446Syntax: 11447""""""" 11448 11449:: 11450 11451 <result> = phi [fast-math-flags] <ty> [ <val0>, <label0>], ... 11452 11453Overview: 11454""""""""" 11455 11456The '``phi``' instruction is used to implement the φ node in the SSA 11457graph representing the function. 11458 11459Arguments: 11460"""""""""" 11461 11462The type of the incoming values is specified with the first type field. 11463After this, the '``phi``' instruction takes a list of pairs as 11464arguments, with one pair for each predecessor basic block of the current 11465block. Only values of :ref:`first class <t_firstclass>` type may be used as 11466the value arguments to the PHI node. Only labels may be used as the 11467label arguments. 11468 11469There must be no non-phi instructions between the start of a basic block 11470and the PHI instructions: i.e. PHI instructions must be first in a basic 11471block. 11472 11473For the purposes of the SSA form, the use of each incoming value is 11474deemed to occur on the edge from the corresponding predecessor block to 11475the current block (but after any definition of an '``invoke``' 11476instruction's return value on the same edge). 11477 11478The optional ``fast-math-flags`` marker indicates that the phi has one 11479or more :ref:`fast-math-flags <fastmath>`. These are optimization hints 11480to enable otherwise unsafe floating-point optimizations. Fast-math-flags 11481are only valid for phis that return a floating-point scalar or vector 11482type, or an array (nested to any depth) of floating-point scalar or vector 11483types. 11484 11485Semantics: 11486"""""""""" 11487 11488At runtime, the '``phi``' instruction logically takes on the value 11489specified by the pair corresponding to the predecessor basic block that 11490executed just prior to the current block. 11491 11492Example: 11493"""""""" 11494 11495.. code-block:: llvm 11496 11497 Loop: ; Infinite loop that counts from 0 on up... 11498 %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ] 11499 %nextindvar = add i32 %indvar, 1 11500 br label %Loop 11501 11502.. _i_select: 11503 11504'``select``' Instruction 11505^^^^^^^^^^^^^^^^^^^^^^^^ 11506 11507Syntax: 11508""""""" 11509 11510:: 11511 11512 <result> = select [fast-math flags] selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty 11513 11514 selty is either i1 or {<N x i1>} 11515 11516Overview: 11517""""""""" 11518 11519The '``select``' instruction is used to choose one value based on a 11520condition, without IR-level branching. 11521 11522Arguments: 11523"""""""""" 11524 11525The '``select``' instruction requires an 'i1' value or a vector of 'i1' 11526values indicating the condition, and two values of the same :ref:`first 11527class <t_firstclass>` type. 11528 11529#. The optional ``fast-math flags`` marker indicates that the select has one or more 11530 :ref:`fast-math flags <fastmath>`. These are optimization hints to enable 11531 otherwise unsafe floating-point optimizations. Fast-math flags are only valid 11532 for selects that return a floating-point scalar or vector type, or an array 11533 (nested to any depth) of floating-point scalar or vector types. 11534 11535Semantics: 11536"""""""""" 11537 11538If the condition is an i1 and it evaluates to 1, the instruction returns 11539the first value argument; otherwise, it returns the second value 11540argument. 11541 11542If the condition is a vector of i1, then the value arguments must be 11543vectors of the same size, and the selection is done element by element. 11544 11545If the condition is an i1 and the value arguments are vectors of the 11546same size, then an entire vector is selected. 11547 11548Example: 11549"""""""" 11550 11551.. code-block:: llvm 11552 11553 %X = select i1 true, i8 17, i8 42 ; yields i8:17 11554 11555 11556.. _i_freeze: 11557 11558'``freeze``' Instruction 11559^^^^^^^^^^^^^^^^^^^^^^^^ 11560 11561Syntax: 11562""""""" 11563 11564:: 11565 11566 <result> = freeze ty <val> ; yields ty:result 11567 11568Overview: 11569""""""""" 11570 11571The '``freeze``' instruction is used to stop propagation of 11572:ref:`undef <undefvalues>` and :ref:`poison <poisonvalues>` values. 11573 11574Arguments: 11575"""""""""" 11576 11577The '``freeze``' instruction takes a single argument. 11578 11579Semantics: 11580"""""""""" 11581 11582If the argument is ``undef`` or ``poison``, '``freeze``' returns an 11583arbitrary, but fixed, value of type '``ty``'. 11584Otherwise, this instruction is a no-op and returns the input argument. 11585All uses of a value returned by the same '``freeze``' instruction are 11586guaranteed to always observe the same value, while different '``freeze``' 11587instructions may yield different values. 11588 11589While ``undef`` and ``poison`` pointers can be frozen, the result is a 11590non-dereferenceable pointer. See the 11591:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more information. 11592If an aggregate value or vector is frozen, the operand is frozen element-wise. 11593The padding of an aggregate isn't considered, since it isn't visible 11594without storing it into memory and loading it with a different type. 11595 11596 11597Example: 11598"""""""" 11599 11600.. code-block:: text 11601 11602 %w = i32 undef 11603 %x = freeze i32 %w 11604 %y = add i32 %w, %w ; undef 11605 %z = add i32 %x, %x ; even number because all uses of %x observe 11606 ; the same value 11607 %x2 = freeze i32 %w 11608 %cmp = icmp eq i32 %x, %x2 ; can be true or false 11609 11610 ; example with vectors 11611 %v = <2 x i32> <i32 undef, i32 poison> 11612 %a = extractelement <2 x i32> %v, i32 0 ; undef 11613 %b = extractelement <2 x i32> %v, i32 1 ; poison 11614 %add = add i32 %a, %a ; undef 11615 11616 %v.fr = freeze <2 x i32> %v ; element-wise freeze 11617 %d = extractelement <2 x i32> %v.fr, i32 0 ; not undef 11618 %add.f = add i32 %d, %d ; even number 11619 11620 ; branching on frozen value 11621 %poison = add nsw i1 %k, undef ; poison 11622 %c = freeze i1 %poison 11623 br i1 %c, label %foo, label %bar ; non-deterministic branch to %foo or %bar 11624 11625 11626.. _i_call: 11627 11628'``call``' Instruction 11629^^^^^^^^^^^^^^^^^^^^^^ 11630 11631Syntax: 11632""""""" 11633 11634:: 11635 11636 <result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)] 11637 <ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ] 11638 11639Overview: 11640""""""""" 11641 11642The '``call``' instruction represents a simple function call. 11643 11644Arguments: 11645"""""""""" 11646 11647This instruction requires several arguments: 11648 11649#. The optional ``tail`` and ``musttail`` markers indicate that the optimizers 11650 should perform tail call optimization. The ``tail`` marker is a hint that 11651 `can be ignored <CodeGenerator.html#sibcallopt>`_. The ``musttail`` marker 11652 means that the call must be tail call optimized in order for the program to 11653 be correct. The ``musttail`` marker provides these guarantees: 11654 11655 #. The call will not cause unbounded stack growth if it is part of a 11656 recursive cycle in the call graph. 11657 #. Arguments with the :ref:`inalloca <attr_inalloca>` or 11658 :ref:`preallocated <attr_preallocated>` attribute are forwarded in place. 11659 #. If the musttail call appears in a function with the ``"thunk"`` attribute 11660 and the caller and callee both have varargs, than any unprototyped 11661 arguments in register or memory are forwarded to the callee. Similarly, 11662 the return value of the callee is returned to the caller's caller, even 11663 if a void return type is in use. 11664 11665 Both markers imply that the callee does not access allocas from the caller. 11666 The ``tail`` marker additionally implies that the callee does not access 11667 varargs from the caller. Calls marked ``musttail`` must obey the following 11668 additional rules: 11669 11670 - The call must immediately precede a :ref:`ret <i_ret>` instruction, 11671 or a pointer bitcast followed by a ret instruction. 11672 - The ret instruction must return the (possibly bitcasted) value 11673 produced by the call, undef, or void. 11674 - The calling conventions of the caller and callee must match. 11675 - The callee must be varargs iff the caller is varargs. Bitcasting a 11676 non-varargs function to the appropriate varargs type is legal so 11677 long as the non-varargs prefixes obey the other rules. 11678 - The return type must not undergo automatic conversion to an `sret` pointer. 11679 11680 In addition, if the calling convention is not `swifttailcc` or `tailcc`: 11681 11682 - All ABI-impacting function attributes, such as sret, byval, inreg, 11683 returned, and inalloca, must match. 11684 - The caller and callee prototypes must match. Pointer types of parameters 11685 or return types may differ in pointee type, but not in address space. 11686 11687 On the other hand, if the calling convention is `swifttailcc` or `swiftcc`: 11688 11689 - Only these ABI-impacting attributes attributes are allowed: sret, byval, 11690 swiftself, and swiftasync. 11691 - Prototypes are not required to match. 11692 11693 Tail call optimization for calls marked ``tail`` is guaranteed to occur if 11694 the following conditions are met: 11695 11696 - Caller and callee both have the calling convention ``fastcc`` or ``tailcc``. 11697 - The call is in tail position (ret immediately follows call and ret 11698 uses value of call or is void). 11699 - Option ``-tailcallopt`` is enabled, 11700 ``llvm::GuaranteedTailCallOpt`` is ``true``, or the calling convention 11701 is ``tailcc`` 11702 - `Platform-specific constraints are 11703 met. <CodeGenerator.html#tailcallopt>`_ 11704 11705#. The optional ``notail`` marker indicates that the optimizers should not add 11706 ``tail`` or ``musttail`` markers to the call. It is used to prevent tail 11707 call optimization from being performed on the call. 11708 11709#. The optional ``fast-math flags`` marker indicates that the call has one or more 11710 :ref:`fast-math flags <fastmath>`, which are optimization hints to enable 11711 otherwise unsafe floating-point optimizations. Fast-math flags are only valid 11712 for calls that return a floating-point scalar or vector type, or an array 11713 (nested to any depth) of floating-point scalar or vector types. 11714 11715#. The optional "cconv" marker indicates which :ref:`calling 11716 convention <callingconv>` the call should use. If none is 11717 specified, the call defaults to using C calling conventions. The 11718 calling convention of the call must match the calling convention of 11719 the target function, or else the behavior is undefined. 11720#. The optional :ref:`Parameter Attributes <paramattrs>` list for return 11721 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes 11722 are valid here. 11723#. The optional addrspace attribute can be used to indicate the address space 11724 of the called function. If it is not specified, the program address space 11725 from the :ref:`datalayout string<langref_datalayout>` will be used. 11726#. '``ty``': the type of the call instruction itself which is also the 11727 type of the return value. Functions that return no value are marked 11728 ``void``. 11729#. '``fnty``': shall be the signature of the function being called. The 11730 argument types must match the types implied by this signature. This 11731 type can be omitted if the function is not varargs. 11732#. '``fnptrval``': An LLVM value containing a pointer to a function to 11733 be called. In most cases, this is a direct function call, but 11734 indirect ``call``'s are just as possible, calling an arbitrary pointer 11735 to function value. 11736#. '``function args``': argument list whose types match the function 11737 signature argument types and parameter attributes. All arguments must 11738 be of :ref:`first class <t_firstclass>` type. If the function signature 11739 indicates the function accepts a variable number of arguments, the 11740 extra arguments can be specified. 11741#. The optional :ref:`function attributes <fnattrs>` list. 11742#. The optional :ref:`operand bundles <opbundles>` list. 11743 11744Semantics: 11745"""""""""" 11746 11747The '``call``' instruction is used to cause control flow to transfer to 11748a specified function, with its incoming arguments bound to the specified 11749values. Upon a '``ret``' instruction in the called function, control 11750flow continues with the instruction after the function call, and the 11751return value of the function is bound to the result argument. 11752 11753Example: 11754"""""""" 11755 11756.. code-block:: llvm 11757 11758 %retval = call i32 @test(i32 %argc) 11759 call i32 (ptr, ...) @printf(ptr %msg, i32 12, i8 42) ; yields i32 11760 %X = tail call i32 @foo() ; yields i32 11761 %Y = tail call fastcc i32 @foo() ; yields i32 11762 call void %foo(i8 signext 97) 11763 11764 %struct.A = type { i32, i8 } 11765 %r = call %struct.A @foo() ; yields { i32, i8 } 11766 %gr = extractvalue %struct.A %r, 0 ; yields i32 11767 %gr1 = extractvalue %struct.A %r, 1 ; yields i8 11768 %Z = call void @foo() noreturn ; indicates that %foo never returns normally 11769 %ZZ = call zeroext i32 @bar() ; Return value is %zero extended 11770 11771llvm treats calls to some functions with names and arguments that match 11772the standard C99 library as being the C99 library functions, and may 11773perform optimizations or generate code for them under that assumption. 11774This is something we'd like to change in the future to provide better 11775support for freestanding environments and non-C-based languages. 11776 11777.. _i_va_arg: 11778 11779'``va_arg``' Instruction 11780^^^^^^^^^^^^^^^^^^^^^^^^ 11781 11782Syntax: 11783""""""" 11784 11785:: 11786 11787 <resultval> = va_arg <va_list*> <arglist>, <argty> 11788 11789Overview: 11790""""""""" 11791 11792The '``va_arg``' instruction is used to access arguments passed through 11793the "variable argument" area of a function call. It is used to implement 11794the ``va_arg`` macro in C. 11795 11796Arguments: 11797"""""""""" 11798 11799This instruction takes a ``va_list*`` value and the type of the 11800argument. It returns a value of the specified argument type and 11801increments the ``va_list`` to point to the next argument. The actual 11802type of ``va_list`` is target specific. 11803 11804Semantics: 11805"""""""""" 11806 11807The '``va_arg``' instruction loads an argument of the specified type 11808from the specified ``va_list`` and causes the ``va_list`` to point to 11809the next argument. For more information, see the variable argument 11810handling :ref:`Intrinsic Functions <int_varargs>`. 11811 11812It is legal for this instruction to be called in a function which does 11813not take a variable number of arguments, for example, the ``vfprintf`` 11814function. 11815 11816``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic 11817function <intrinsics>` because it takes a type as an argument. 11818 11819Example: 11820"""""""" 11821 11822See the :ref:`variable argument processing <int_varargs>` section. 11823 11824Note that the code generator does not yet fully support va\_arg on many 11825targets. Also, it does not currently support va\_arg with aggregate 11826types on any target. 11827 11828.. _i_landingpad: 11829 11830'``landingpad``' Instruction 11831^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11832 11833Syntax: 11834""""""" 11835 11836:: 11837 11838 <resultval> = landingpad <resultty> <clause>+ 11839 <resultval> = landingpad <resultty> cleanup <clause>* 11840 11841 <clause> := catch <type> <value> 11842 <clause> := filter <array constant type> <array constant> 11843 11844Overview: 11845""""""""" 11846 11847The '``landingpad``' instruction is used by `LLVM's exception handling 11848system <ExceptionHandling.html#overview>`_ to specify that a basic block 11849is a landing pad --- one where the exception lands, and corresponds to the 11850code found in the ``catch`` portion of a ``try``/``catch`` sequence. It 11851defines values supplied by the :ref:`personality function <personalityfn>` upon 11852re-entry to the function. The ``resultval`` has the type ``resultty``. 11853 11854Arguments: 11855"""""""""" 11856 11857The optional 11858``cleanup`` flag indicates that the landing pad block is a cleanup. 11859 11860A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and 11861contains the global variable representing the "type" that may be caught 11862or filtered respectively. Unlike the ``catch`` clause, the ``filter`` 11863clause takes an array constant as its argument. Use 11864"``[0 x ptr] undef``" for a filter which cannot throw. The 11865'``landingpad``' instruction must contain *at least* one ``clause`` or 11866the ``cleanup`` flag. 11867 11868Semantics: 11869"""""""""" 11870 11871The '``landingpad``' instruction defines the values which are set by the 11872:ref:`personality function <personalityfn>` upon re-entry to the function, and 11873therefore the "result type" of the ``landingpad`` instruction. As with 11874calling conventions, how the personality function results are 11875represented in LLVM IR is target specific. 11876 11877The clauses are applied in order from top to bottom. If two 11878``landingpad`` instructions are merged together through inlining, the 11879clauses from the calling function are appended to the list of clauses. 11880When the call stack is being unwound due to an exception being thrown, 11881the exception is compared against each ``clause`` in turn. If it doesn't 11882match any of the clauses, and the ``cleanup`` flag is not set, then 11883unwinding continues further up the call stack. 11884 11885The ``landingpad`` instruction has several restrictions: 11886 11887- A landing pad block is a basic block which is the unwind destination 11888 of an '``invoke``' instruction. 11889- A landing pad block must have a '``landingpad``' instruction as its 11890 first non-PHI instruction. 11891- There can be only one '``landingpad``' instruction within the landing 11892 pad block. 11893- A basic block that is not a landing pad block may not include a 11894 '``landingpad``' instruction. 11895 11896Example: 11897"""""""" 11898 11899.. code-block:: llvm 11900 11901 ;; A landing pad which can catch an integer. 11902 %res = landingpad { ptr, i32 } 11903 catch ptr @_ZTIi 11904 ;; A landing pad that is a cleanup. 11905 %res = landingpad { ptr, i32 } 11906 cleanup 11907 ;; A landing pad which can catch an integer and can only throw a double. 11908 %res = landingpad { ptr, i32 } 11909 catch ptr @_ZTIi 11910 filter [1 x ptr] [ptr @_ZTId] 11911 11912.. _i_catchpad: 11913 11914'``catchpad``' Instruction 11915^^^^^^^^^^^^^^^^^^^^^^^^^^ 11916 11917Syntax: 11918""""""" 11919 11920:: 11921 11922 <resultval> = catchpad within <catchswitch> [<args>*] 11923 11924Overview: 11925""""""""" 11926 11927The '``catchpad``' instruction is used by `LLVM's exception handling 11928system <ExceptionHandling.html#overview>`_ to specify that a basic block 11929begins a catch handler --- one where a personality routine attempts to transfer 11930control to catch an exception. 11931 11932Arguments: 11933"""""""""" 11934 11935The ``catchswitch`` operand must always be a token produced by a 11936:ref:`catchswitch <i_catchswitch>` instruction in a predecessor block. This 11937ensures that each ``catchpad`` has exactly one predecessor block, and it always 11938terminates in a ``catchswitch``. 11939 11940The ``args`` correspond to whatever information the personality routine 11941requires to know if this is an appropriate handler for the exception. Control 11942will transfer to the ``catchpad`` if this is the first appropriate handler for 11943the exception. 11944 11945The ``resultval`` has the type :ref:`token <t_token>` and is used to match the 11946``catchpad`` to corresponding :ref:`catchrets <i_catchret>` and other nested EH 11947pads. 11948 11949Semantics: 11950"""""""""" 11951 11952When the call stack is being unwound due to an exception being thrown, the 11953exception is compared against the ``args``. If it doesn't match, control will 11954not reach the ``catchpad`` instruction. The representation of ``args`` is 11955entirely target and personality function-specific. 11956 11957Like the :ref:`landingpad <i_landingpad>` instruction, the ``catchpad`` 11958instruction must be the first non-phi of its parent basic block. 11959 11960The meaning of the tokens produced and consumed by ``catchpad`` and other "pad" 11961instructions is described in the 11962`Windows exception handling documentation\ <ExceptionHandling.html#wineh>`_. 11963 11964When a ``catchpad`` has been "entered" but not yet "exited" (as 11965described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 11966it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 11967that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`. 11968 11969Example: 11970"""""""" 11971 11972.. code-block:: text 11973 11974 dispatch: 11975 %cs = catchswitch within none [label %handler0] unwind to caller 11976 ;; A catch block which can catch an integer. 11977 handler0: 11978 %tok = catchpad within %cs [ptr @_ZTIi] 11979 11980.. _i_cleanuppad: 11981 11982'``cleanuppad``' Instruction 11983^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 11984 11985Syntax: 11986""""""" 11987 11988:: 11989 11990 <resultval> = cleanuppad within <parent> [<args>*] 11991 11992Overview: 11993""""""""" 11994 11995The '``cleanuppad``' instruction is used by `LLVM's exception handling 11996system <ExceptionHandling.html#overview>`_ to specify that a basic block 11997is a cleanup block --- one where a personality routine attempts to 11998transfer control to run cleanup actions. 11999The ``args`` correspond to whatever additional 12000information the :ref:`personality function <personalityfn>` requires to 12001execute the cleanup. 12002The ``resultval`` has the type :ref:`token <t_token>` and is used to 12003match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`. 12004The ``parent`` argument is the token of the funclet that contains the 12005``cleanuppad`` instruction. If the ``cleanuppad`` is not inside a funclet, 12006this operand may be the token ``none``. 12007 12008Arguments: 12009"""""""""" 12010 12011The instruction takes a list of arbitrary values which are interpreted 12012by the :ref:`personality function <personalityfn>`. 12013 12014Semantics: 12015"""""""""" 12016 12017When the call stack is being unwound due to an exception being thrown, 12018the :ref:`personality function <personalityfn>` transfers control to the 12019``cleanuppad`` with the aid of the personality-specific arguments. 12020As with calling conventions, how the personality function results are 12021represented in LLVM IR is target specific. 12022 12023The ``cleanuppad`` instruction has several restrictions: 12024 12025- A cleanup block is a basic block which is the unwind destination of 12026 an exceptional instruction. 12027- A cleanup block must have a '``cleanuppad``' instruction as its 12028 first non-PHI instruction. 12029- There can be only one '``cleanuppad``' instruction within the 12030 cleanup block. 12031- A basic block that is not a cleanup block may not include a 12032 '``cleanuppad``' instruction. 12033 12034When a ``cleanuppad`` has been "entered" but not yet "exited" (as 12035described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_), 12036it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>` 12037that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`. 12038 12039Example: 12040"""""""" 12041 12042.. code-block:: text 12043 12044 %tok = cleanuppad within %cs [] 12045 12046.. _intrinsics: 12047 12048Intrinsic Functions 12049=================== 12050 12051LLVM supports the notion of an "intrinsic function". These functions 12052have well known names and semantics and are required to follow certain 12053restrictions. Overall, these intrinsics represent an extension mechanism 12054for the LLVM language that does not require changing all of the 12055transformations in LLVM when adding to the language (or the bitcode 12056reader/writer, the parser, etc...). 12057 12058Intrinsic function names must all start with an "``llvm.``" prefix. This 12059prefix is reserved in LLVM for intrinsic names; thus, function names may 12060not begin with this prefix. Intrinsic functions must always be external 12061functions: you cannot define the body of intrinsic functions. Intrinsic 12062functions may only be used in call or invoke instructions: it is illegal 12063to take the address of an intrinsic function. Additionally, because 12064intrinsic functions are part of the LLVM language, it is required if any 12065are added that they be documented here. 12066 12067Some intrinsic functions can be overloaded, i.e., the intrinsic 12068represents a family of functions that perform the same operation but on 12069different data types. Because LLVM can represent over 8 million 12070different integer types, overloading is used commonly to allow an 12071intrinsic function to operate on any integer type. One or more of the 12072argument types or the result type can be overloaded to accept any 12073integer type. Argument types may also be defined as exactly matching a 12074previous argument's type or the result type. This allows an intrinsic 12075function which accepts multiple arguments, but needs all of them to be 12076of the same type, to only be overloaded with respect to a single 12077argument or the result. 12078 12079Overloaded intrinsics will have the names of its overloaded argument 12080types encoded into its function name, each preceded by a period. Only 12081those types which are overloaded result in a name suffix. Arguments 12082whose type is matched against another type do not. For example, the 12083``llvm.ctpop`` function can take an integer of any width and returns an 12084integer of exactly the same integer width. This leads to a family of 12085functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and 12086``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is 12087overloaded, and only one type suffix is required. Because the argument's 12088type is matched against the return type, it does not require its own 12089name suffix. 12090 12091:ref:`Unnamed types <t_opaque>` are encoded as ``s_s``. Overloaded intrinsics 12092that depend on an unnamed type in one of its overloaded argument types get an 12093additional ``.<number>`` suffix. This allows differentiating intrinsics with 12094different unnamed types as arguments. (For example: 12095``llvm.ssa.copy.p0s_s.2(%42*)``) The number is tracked in the LLVM module and 12096it ensures unique names in the module. While linking together two modules, it is 12097still possible to get a name clash. In that case one of the names will be 12098changed by getting a new number. 12099 12100For target developers who are defining intrinsics for back-end code 12101generation, any intrinsic overloads based solely the distinction between 12102integer or floating point types should not be relied upon for correct 12103code generation. In such cases, the recommended approach for target 12104maintainers when defining intrinsics is to create separate integer and 12105FP intrinsics rather than rely on overloading. For example, if different 12106codegen is required for ``llvm.target.foo(<4 x i32>)`` and 12107``llvm.target.foo(<4 x float>)`` then these should be split into 12108different intrinsics. 12109 12110To learn how to add an intrinsic function, please see the `Extending 12111LLVM Guide <ExtendingLLVM.html>`_. 12112 12113.. _int_varargs: 12114 12115Variable Argument Handling Intrinsics 12116------------------------------------- 12117 12118Variable argument support is defined in LLVM with the 12119:ref:`va_arg <i_va_arg>` instruction and these three intrinsic 12120functions. These functions are related to the similarly named macros 12121defined in the ``<stdarg.h>`` header file. 12122 12123All of these functions operate on arguments that use a target-specific 12124value type "``va_list``". The LLVM assembly language reference manual 12125does not define what this type is, so all transformations should be 12126prepared to handle these functions regardless of the type used. 12127 12128This example shows how the :ref:`va_arg <i_va_arg>` instruction and the 12129variable argument handling intrinsic functions are used. 12130 12131.. code-block:: llvm 12132 12133 ; This struct is different for every platform. For most platforms, 12134 ; it is merely a ptr. 12135 %struct.va_list = type { ptr } 12136 12137 ; For Unix x86_64 platforms, va_list is the following struct: 12138 ; %struct.va_list = type { i32, i32, ptr, ptr } 12139 12140 define i32 @test(i32 %X, ...) { 12141 ; Initialize variable argument processing 12142 %ap = alloca %struct.va_list 12143 call void @llvm.va_start(ptr %ap) 12144 12145 ; Read a single integer argument 12146 %tmp = va_arg ptr %ap, i32 12147 12148 ; Demonstrate usage of llvm.va_copy and llvm.va_end 12149 %aq = alloca ptr 12150 call void @llvm.va_copy(ptr %aq, ptr %ap) 12151 call void @llvm.va_end(ptr %aq) 12152 12153 ; Stop processing of arguments. 12154 call void @llvm.va_end(ptr %ap) 12155 ret i32 %tmp 12156 } 12157 12158 declare void @llvm.va_start(ptr) 12159 declare void @llvm.va_copy(ptr, ptr) 12160 declare void @llvm.va_end(ptr) 12161 12162.. _int_va_start: 12163 12164'``llvm.va_start``' Intrinsic 12165^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12166 12167Syntax: 12168""""""" 12169 12170:: 12171 12172 declare void @llvm.va_start(ptr <arglist>) 12173 12174Overview: 12175""""""""" 12176 12177The '``llvm.va_start``' intrinsic initializes ``<arglist>`` for 12178subsequent use by ``va_arg``. 12179 12180Arguments: 12181"""""""""" 12182 12183The argument is a pointer to a ``va_list`` element to initialize. 12184 12185Semantics: 12186"""""""""" 12187 12188The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro 12189available in C. In a target-dependent way, it initializes the 12190``va_list`` element to which the argument points, so that the next call 12191to ``va_arg`` will produce the first variable argument passed to the 12192function. Unlike the C ``va_start`` macro, this intrinsic does not need 12193to know the last argument of the function as the compiler can figure 12194that out. 12195 12196'``llvm.va_end``' Intrinsic 12197^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12198 12199Syntax: 12200""""""" 12201 12202:: 12203 12204 declare void @llvm.va_end(ptr <arglist>) 12205 12206Overview: 12207""""""""" 12208 12209The '``llvm.va_end``' intrinsic destroys ``<arglist>``, which has been 12210initialized previously with ``llvm.va_start`` or ``llvm.va_copy``. 12211 12212Arguments: 12213"""""""""" 12214 12215The argument is a pointer to a ``va_list`` to destroy. 12216 12217Semantics: 12218"""""""""" 12219 12220The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro 12221available in C. In a target-dependent way, it destroys the ``va_list`` 12222element to which the argument points. Calls to 12223:ref:`llvm.va_start <int_va_start>` and 12224:ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to 12225``llvm.va_end``. 12226 12227.. _int_va_copy: 12228 12229'``llvm.va_copy``' Intrinsic 12230^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12231 12232Syntax: 12233""""""" 12234 12235:: 12236 12237 declare void @llvm.va_copy(ptr <destarglist>, ptr <srcarglist>) 12238 12239Overview: 12240""""""""" 12241 12242The '``llvm.va_copy``' intrinsic copies the current argument position 12243from the source argument list to the destination argument list. 12244 12245Arguments: 12246"""""""""" 12247 12248The first argument is a pointer to a ``va_list`` element to initialize. 12249The second argument is a pointer to a ``va_list`` element to copy from. 12250 12251Semantics: 12252"""""""""" 12253 12254The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro 12255available in C. In a target-dependent way, it copies the source 12256``va_list`` element into the destination ``va_list`` element. This 12257intrinsic is necessary because the `` llvm.va_start`` intrinsic may be 12258arbitrarily complex and require, for example, memory allocation. 12259 12260Accurate Garbage Collection Intrinsics 12261-------------------------------------- 12262 12263LLVM's support for `Accurate Garbage Collection <GarbageCollection.html>`_ 12264(GC) requires the frontend to generate code containing appropriate intrinsic 12265calls and select an appropriate GC strategy which knows how to lower these 12266intrinsics in a manner which is appropriate for the target collector. 12267 12268These intrinsics allow identification of :ref:`GC roots on the 12269stack <int_gcroot>`, as well as garbage collector implementations that 12270require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. 12271Frontends for type-safe garbage collected languages should generate 12272these intrinsics to make use of the LLVM garbage collectors. For more 12273details, see `Garbage Collection with LLVM <GarbageCollection.html>`_. 12274 12275LLVM provides an second experimental set of intrinsics for describing garbage 12276collection safepoints in compiled code. These intrinsics are an alternative 12277to the ``llvm.gcroot`` intrinsics, but are compatible with the ones for 12278:ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. The 12279differences in approach are covered in the `Garbage Collection with LLVM 12280<GarbageCollection.html>`_ documentation. The intrinsics themselves are 12281described in :doc:`Statepoints`. 12282 12283.. _int_gcroot: 12284 12285'``llvm.gcroot``' Intrinsic 12286^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12287 12288Syntax: 12289""""""" 12290 12291:: 12292 12293 declare void @llvm.gcroot(ptr %ptrloc, ptr %metadata) 12294 12295Overview: 12296""""""""" 12297 12298The '``llvm.gcroot``' intrinsic declares the existence of a GC root to 12299the code generator, and allows some metadata to be associated with it. 12300 12301Arguments: 12302"""""""""" 12303 12304The first argument specifies the address of a stack object that contains 12305the root pointer. The second pointer (which must be either a constant or 12306a global value address) contains the meta-data to be associated with the 12307root. 12308 12309Semantics: 12310"""""""""" 12311 12312At runtime, a call to this intrinsic stores a null pointer into the 12313"ptrloc" location. At compile-time, the code generator generates 12314information to allow the runtime to find the pointer at GC safe points. 12315The '``llvm.gcroot``' intrinsic may only be used in a function which 12316:ref:`specifies a GC algorithm <gc>`. 12317 12318.. _int_gcread: 12319 12320'``llvm.gcread``' Intrinsic 12321^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12322 12323Syntax: 12324""""""" 12325 12326:: 12327 12328 declare ptr @llvm.gcread(ptr %ObjPtr, ptr %Ptr) 12329 12330Overview: 12331""""""""" 12332 12333The '``llvm.gcread``' intrinsic identifies reads of references from heap 12334locations, allowing garbage collector implementations that require read 12335barriers. 12336 12337Arguments: 12338"""""""""" 12339 12340The second argument is the address to read from, which should be an 12341address allocated from the garbage collector. The first object is a 12342pointer to the start of the referenced object, if needed by the language 12343runtime (otherwise null). 12344 12345Semantics: 12346"""""""""" 12347 12348The '``llvm.gcread``' intrinsic has the same semantics as a load 12349instruction, but may be replaced with substantially more complex code by 12350the garbage collector runtime, as needed. The '``llvm.gcread``' 12351intrinsic may only be used in a function which :ref:`specifies a GC 12352algorithm <gc>`. 12353 12354.. _int_gcwrite: 12355 12356'``llvm.gcwrite``' Intrinsic 12357^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12358 12359Syntax: 12360""""""" 12361 12362:: 12363 12364 declare void @llvm.gcwrite(ptr %P1, ptr %Obj, ptr %P2) 12365 12366Overview: 12367""""""""" 12368 12369The '``llvm.gcwrite``' intrinsic identifies writes of references to heap 12370locations, allowing garbage collector implementations that require write 12371barriers (such as generational or reference counting collectors). 12372 12373Arguments: 12374"""""""""" 12375 12376The first argument is the reference to store, the second is the start of 12377the object to store it to, and the third is the address of the field of 12378Obj to store to. If the runtime does not require a pointer to the 12379object, Obj may be null. 12380 12381Semantics: 12382"""""""""" 12383 12384The '``llvm.gcwrite``' intrinsic has the same semantics as a store 12385instruction, but may be replaced with substantially more complex code by 12386the garbage collector runtime, as needed. The '``llvm.gcwrite``' 12387intrinsic may only be used in a function which :ref:`specifies a GC 12388algorithm <gc>`. 12389 12390 12391.. _gc_statepoint: 12392 12393'llvm.experimental.gc.statepoint' Intrinsic 12394^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12395 12396Syntax: 12397""""""" 12398 12399:: 12400 12401 declare token 12402 @llvm.experimental.gc.statepoint(i64 <id>, i32 <num patch bytes>, 12403 ptr elementtype(func_type) <target>, 12404 i64 <#call args>, i64 <flags>, 12405 ... (call parameters), 12406 i64 0, i64 0) 12407 12408Overview: 12409""""""""" 12410 12411The statepoint intrinsic represents a call which is parse-able by the 12412runtime. 12413 12414Operands: 12415""""""""" 12416 12417The 'id' operand is a constant integer that is reported as the ID 12418field in the generated stackmap. LLVM does not interpret this 12419parameter in any way and its meaning is up to the statepoint user to 12420decide. Note that LLVM is free to duplicate code containing 12421statepoint calls, and this may transform IR that had a unique 'id' per 12422lexical call to statepoint to IR that does not. 12423 12424If 'num patch bytes' is non-zero then the call instruction 12425corresponding to the statepoint is not emitted and LLVM emits 'num 12426patch bytes' bytes of nops in its place. LLVM will emit code to 12427prepare the function arguments and retrieve the function return value 12428in accordance to the calling convention; the former before the nop 12429sequence and the latter after the nop sequence. It is expected that 12430the user will patch over the 'num patch bytes' bytes of nops with a 12431calling sequence specific to their runtime before executing the 12432generated machine code. There are no guarantees with respect to the 12433alignment of the nop sequence. Unlike :doc:`StackMaps` statepoints do 12434not have a concept of shadow bytes. Note that semantically the 12435statepoint still represents a call or invoke to 'target', and the nop 12436sequence after patching is expected to represent an operation 12437equivalent to a call or invoke to 'target'. 12438 12439The 'target' operand is the function actually being called. The operand 12440must have an :ref:`elementtype <attr_elementtype>` attribute specifying 12441the function type of the target. The target can be specified as either 12442a symbolic LLVM function, or as an arbitrary Value of pointer type. Note 12443that the function type must match the signature of the callee and the 12444types of the 'call parameters' arguments. 12445 12446The '#call args' operand is the number of arguments to the actual 12447call. It must exactly match the number of arguments passed in the 12448'call parameters' variable length section. 12449 12450The 'flags' operand is used to specify extra information about the 12451statepoint. This is currently only used to mark certain statepoints 12452as GC transitions. This operand is a 64-bit integer with the following 12453layout, where bit 0 is the least significant bit: 12454 12455 +-------+---------------------------------------------------+ 12456 | Bit # | Usage | 12457 +=======+===================================================+ 12458 | 0 | Set if the statepoint is a GC transition, cleared | 12459 | | otherwise. | 12460 +-------+---------------------------------------------------+ 12461 | 1-63 | Reserved for future use; must be cleared. | 12462 +-------+---------------------------------------------------+ 12463 12464The 'call parameters' arguments are simply the arguments which need to 12465be passed to the call target. They will be lowered according to the 12466specified calling convention and otherwise handled like a normal call 12467instruction. The number of arguments must exactly match what is 12468specified in '# call args'. The types must match the signature of 12469'target'. 12470 12471The 'call parameter' attributes must be followed by two 'i64 0' constants. 12472These were originally the length prefixes for 'gc transition parameter' and 12473'deopt parameter' arguments, but the role of these parameter sets have been 12474entirely replaced with the corresponding operand bundles. In a future 12475revision, these now redundant arguments will be removed. 12476 12477Semantics: 12478"""""""""" 12479 12480A statepoint is assumed to read and write all memory. As a result, 12481memory operations can not be reordered past a statepoint. It is 12482illegal to mark a statepoint as being either 'readonly' or 'readnone'. 12483 12484Note that legal IR can not perform any memory operation on a 'gc 12485pointer' argument of the statepoint in a location statically reachable 12486from the statepoint. Instead, the explicitly relocated value (from a 12487``gc.relocate``) must be used. 12488 12489'llvm.experimental.gc.result' Intrinsic 12490^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12491 12492Syntax: 12493""""""" 12494 12495:: 12496 12497 declare type 12498 @llvm.experimental.gc.result(token %statepoint_token) 12499 12500Overview: 12501""""""""" 12502 12503``gc.result`` extracts the result of the original call instruction 12504which was replaced by the ``gc.statepoint``. The ``gc.result`` 12505intrinsic is actually a family of three intrinsics due to an 12506implementation limitation. Other than the type of the return value, 12507the semantics are the same. 12508 12509Operands: 12510""""""""" 12511 12512The first and only argument is the ``gc.statepoint`` which starts 12513the safepoint sequence of which this ``gc.result`` is a part. 12514Despite the typing of this as a generic token, *only* the value defined 12515by a ``gc.statepoint`` is legal here. 12516 12517Semantics: 12518"""""""""" 12519 12520The ``gc.result`` represents the return value of the call target of 12521the ``statepoint``. The type of the ``gc.result`` must exactly match 12522the type of the target. If the call target returns void, there will 12523be no ``gc.result``. 12524 12525A ``gc.result`` is modeled as a 'readnone' pure function. It has no 12526side effects since it is just a projection of the return value of the 12527previous call represented by the ``gc.statepoint``. 12528 12529'llvm.experimental.gc.relocate' Intrinsic 12530^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12531 12532Syntax: 12533""""""" 12534 12535:: 12536 12537 declare <pointer type> 12538 @llvm.experimental.gc.relocate(token %statepoint_token, 12539 i32 %base_offset, 12540 i32 %pointer_offset) 12541 12542Overview: 12543""""""""" 12544 12545A ``gc.relocate`` returns the potentially relocated value of a pointer 12546at the safepoint. 12547 12548Operands: 12549""""""""" 12550 12551The first argument is the ``gc.statepoint`` which starts the 12552safepoint sequence of which this ``gc.relocation`` is a part. 12553Despite the typing of this as a generic token, *only* the value defined 12554by a ``gc.statepoint`` is legal here. 12555 12556The second and third arguments are both indices into operands of the 12557corresponding statepoint's :ref:`gc-live <ob_gc_live>` operand bundle. 12558 12559The second argument is an index which specifies the allocation for the pointer 12560being relocated. The associated value must be within the object with which the 12561pointer being relocated is associated. The optimizer is free to change *which* 12562interior derived pointer is reported, provided that it does not replace an 12563actual base pointer with another interior derived pointer. Collectors are 12564allowed to rely on the base pointer operand remaining an actual base pointer if 12565so constructed. 12566 12567The third argument is an index which specify the (potentially) derived pointer 12568being relocated. It is legal for this index to be the same as the second 12569argument if-and-only-if a base pointer is being relocated. 12570 12571Semantics: 12572"""""""""" 12573 12574The return value of ``gc.relocate`` is the potentially relocated value 12575of the pointer specified by its arguments. It is unspecified how the 12576value of the returned pointer relates to the argument to the 12577``gc.statepoint`` other than that a) it points to the same source 12578language object with the same offset, and b) the 'based-on' 12579relationship of the newly relocated pointers is a projection of the 12580unrelocated pointers. In particular, the integer value of the pointer 12581returned is unspecified. 12582 12583A ``gc.relocate`` is modeled as a ``readnone`` pure function. It has no 12584side effects since it is just a way to extract information about work 12585done during the actual call modeled by the ``gc.statepoint``. 12586 12587.. _gc.get.pointer.base: 12588 12589'llvm.experimental.gc.get.pointer.base' Intrinsic 12590^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12591 12592Syntax: 12593""""""" 12594 12595:: 12596 12597 declare <pointer type> 12598 @llvm.experimental.gc.get.pointer.base( 12599 <pointer type> readnone nocapture %derived_ptr) 12600 nounwind readnone willreturn 12601 12602Overview: 12603""""""""" 12604 12605``gc.get.pointer.base`` for a derived pointer returns its base pointer. 12606 12607Operands: 12608""""""""" 12609 12610The only argument is a pointer which is based on some object with 12611an unknown offset from the base of said object. 12612 12613Semantics: 12614"""""""""" 12615 12616This intrinsic is used in the abstract machine model for GC to represent 12617the base pointer for an arbitrary derived pointer. 12618 12619This intrinsic is inlined by the :ref:`RewriteStatepointsForGC` pass by 12620replacing all uses of this callsite with the offset of a derived pointer from 12621its base pointer value. The replacement is done as part of the lowering to the 12622explicit statepoint model. 12623 12624The return pointer type must be the same as the type of the parameter. 12625 12626 12627'llvm.experimental.gc.get.pointer.offset' Intrinsic 12628^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12629 12630Syntax: 12631""""""" 12632 12633:: 12634 12635 declare i64 12636 @llvm.experimental.gc.get.pointer.offset( 12637 <pointer type> readnone nocapture %derived_ptr) 12638 nounwind readnone willreturn 12639 12640Overview: 12641""""""""" 12642 12643``gc.get.pointer.offset`` for a derived pointer returns the offset from its 12644base pointer. 12645 12646Operands: 12647""""""""" 12648 12649The only argument is a pointer which is based on some object with 12650an unknown offset from the base of said object. 12651 12652Semantics: 12653"""""""""" 12654 12655This intrinsic is used in the abstract machine model for GC to represent 12656the offset of an arbitrary derived pointer from its base pointer. 12657 12658This intrinsic is inlined by the :ref:`RewriteStatepointsForGC` pass by 12659replacing all uses of this callsite with the offset of a derived pointer from 12660its base pointer value. The replacement is done as part of the lowering to the 12661explicit statepoint model. 12662 12663Basically this call calculates difference between the derived pointer and its 12664base pointer (see :ref:`gc.get.pointer.base`) both ptrtoint casted. But 12665this cast done outside the :ref:`RewriteStatepointsForGC` pass could result 12666in the pointers lost for further lowering from the abstract model to the 12667explicit physical one. 12668 12669Code Generator Intrinsics 12670------------------------- 12671 12672These intrinsics are provided by LLVM to expose special features that 12673may only be implemented with code generator support. 12674 12675'``llvm.returnaddress``' Intrinsic 12676^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12677 12678Syntax: 12679""""""" 12680 12681:: 12682 12683 declare ptr @llvm.returnaddress(i32 <level>) 12684 12685Overview: 12686""""""""" 12687 12688The '``llvm.returnaddress``' intrinsic attempts to compute a 12689target-specific value indicating the return address of the current 12690function or one of its callers. 12691 12692Arguments: 12693"""""""""" 12694 12695The argument to this intrinsic indicates which function to return the 12696address for. Zero indicates the calling function, one indicates its 12697caller, etc. The argument is **required** to be a constant integer 12698value. 12699 12700Semantics: 12701"""""""""" 12702 12703The '``llvm.returnaddress``' intrinsic either returns a pointer 12704indicating the return address of the specified call frame, or zero if it 12705cannot be identified. The value returned by this intrinsic is likely to 12706be incorrect or 0 for arguments other than zero, so it should only be 12707used for debugging purposes. 12708 12709Note that calling this intrinsic does not prevent function inlining or 12710other aggressive transformations, so the value returned may not be that 12711of the obvious source-language caller. 12712 12713'``llvm.addressofreturnaddress``' Intrinsic 12714^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12715 12716Syntax: 12717""""""" 12718 12719:: 12720 12721 declare ptr @llvm.addressofreturnaddress() 12722 12723Overview: 12724""""""""" 12725 12726The '``llvm.addressofreturnaddress``' intrinsic returns a target-specific 12727pointer to the place in the stack frame where the return address of the 12728current function is stored. 12729 12730Semantics: 12731"""""""""" 12732 12733Note that calling this intrinsic does not prevent function inlining or 12734other aggressive transformations, so the value returned may not be that 12735of the obvious source-language caller. 12736 12737This intrinsic is only implemented for x86 and aarch64. 12738 12739'``llvm.sponentry``' Intrinsic 12740^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12741 12742Syntax: 12743""""""" 12744 12745:: 12746 12747 declare ptr @llvm.sponentry() 12748 12749Overview: 12750""""""""" 12751 12752The '``llvm.sponentry``' intrinsic returns the stack pointer value at 12753the entry of the current function calling this intrinsic. 12754 12755Semantics: 12756"""""""""" 12757 12758Note this intrinsic is only verified on AArch64 and ARM. 12759 12760'``llvm.frameaddress``' Intrinsic 12761^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12762 12763Syntax: 12764""""""" 12765 12766:: 12767 12768 declare ptr @llvm.frameaddress(i32 <level>) 12769 12770Overview: 12771""""""""" 12772 12773The '``llvm.frameaddress``' intrinsic attempts to return the 12774target-specific frame pointer value for the specified stack frame. 12775 12776Arguments: 12777"""""""""" 12778 12779The argument to this intrinsic indicates which function to return the 12780frame pointer for. Zero indicates the calling function, one indicates 12781its caller, etc. The argument is **required** to be a constant integer 12782value. 12783 12784Semantics: 12785"""""""""" 12786 12787The '``llvm.frameaddress``' intrinsic either returns a pointer 12788indicating the frame address of the specified call frame, or zero if it 12789cannot be identified. The value returned by this intrinsic is likely to 12790be incorrect or 0 for arguments other than zero, so it should only be 12791used for debugging purposes. 12792 12793Note that calling this intrinsic does not prevent function inlining or 12794other aggressive transformations, so the value returned may not be that 12795of the obvious source-language caller. 12796 12797'``llvm.swift.async.context.addr``' Intrinsic 12798^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12799 12800Syntax: 12801""""""" 12802 12803:: 12804 12805 declare ptr @llvm.swift.async.context.addr() 12806 12807Overview: 12808""""""""" 12809 12810The '``llvm.swift.async.context.addr``' intrinsic returns a pointer to 12811the part of the extended frame record containing the asynchronous 12812context of a Swift execution. 12813 12814Semantics: 12815"""""""""" 12816 12817If the caller has a ``swiftasync`` parameter, that argument will initially 12818be stored at the returned address. If not, it will be initialized to null. 12819 12820'``llvm.localescape``' and '``llvm.localrecover``' Intrinsics 12821^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12822 12823Syntax: 12824""""""" 12825 12826:: 12827 12828 declare void @llvm.localescape(...) 12829 declare ptr @llvm.localrecover(ptr %func, ptr %fp, i32 %idx) 12830 12831Overview: 12832""""""""" 12833 12834The '``llvm.localescape``' intrinsic escapes offsets of a collection of static 12835allocas, and the '``llvm.localrecover``' intrinsic applies those offsets to a 12836live frame pointer to recover the address of the allocation. The offset is 12837computed during frame layout of the caller of ``llvm.localescape``. 12838 12839Arguments: 12840"""""""""" 12841 12842All arguments to '``llvm.localescape``' must be pointers to static allocas or 12843casts of static allocas. Each function can only call '``llvm.localescape``' 12844once, and it can only do so from the entry block. 12845 12846The ``func`` argument to '``llvm.localrecover``' must be a constant 12847bitcasted pointer to a function defined in the current module. The code 12848generator cannot determine the frame allocation offset of functions defined in 12849other modules. 12850 12851The ``fp`` argument to '``llvm.localrecover``' must be a frame pointer of a 12852call frame that is currently live. The return value of '``llvm.localaddress``' 12853is one way to produce such a value, but various runtimes also expose a suitable 12854pointer in platform-specific ways. 12855 12856The ``idx`` argument to '``llvm.localrecover``' indicates which alloca passed to 12857'``llvm.localescape``' to recover. It is zero-indexed. 12858 12859Semantics: 12860"""""""""" 12861 12862These intrinsics allow a group of functions to share access to a set of local 12863stack allocations of a one parent function. The parent function may call the 12864'``llvm.localescape``' intrinsic once from the function entry block, and the 12865child functions can use '``llvm.localrecover``' to access the escaped allocas. 12866The '``llvm.localescape``' intrinsic blocks inlining, as inlining changes where 12867the escaped allocas are allocated, which would break attempts to use 12868'``llvm.localrecover``'. 12869 12870'``llvm.seh.try.begin``' and '``llvm.seh.try.end``' Intrinsics 12871^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12872 12873Syntax: 12874""""""" 12875 12876:: 12877 12878 declare void @llvm.seh.try.begin() 12879 declare void @llvm.seh.try.end() 12880 12881Overview: 12882""""""""" 12883 12884The '``llvm.seh.try.begin``' and '``llvm.seh.try.end``' intrinsics mark 12885the boundary of a _try region for Windows SEH Asynchrous Exception Handling. 12886 12887Semantics: 12888"""""""""" 12889 12890When a C-function is compiled with Windows SEH Asynchrous Exception option, 12891-feh_asynch (aka MSVC -EHa), these two intrinsics are injected to mark _try 12892boundary and to prevent potential exceptions from being moved across boundary. 12893Any set of operations can then be confined to the region by reading their leaf 12894inputs via volatile loads and writing their root outputs via volatile stores. 12895 12896'``llvm.seh.scope.begin``' and '``llvm.seh.scope.end``' Intrinsics 12897^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12898 12899Syntax: 12900""""""" 12901 12902:: 12903 12904 declare void @llvm.seh.scope.begin() 12905 declare void @llvm.seh.scope.end() 12906 12907Overview: 12908""""""""" 12909 12910The '``llvm.seh.scope.begin``' and '``llvm.seh.scope.end``' intrinsics mark 12911the boundary of a CPP object lifetime for Windows SEH Asynchrous Exception 12912Handling (MSVC option -EHa). 12913 12914Semantics: 12915"""""""""" 12916 12917LLVM's ordinary exception-handling representation associates EH cleanups and 12918handlers only with ``invoke``s, which normally correspond only to call sites. To 12919support arbitrary faulting instructions, it must be possible to recover the current 12920EH scope for any instruction. Turning every operation in LLVM that could fault 12921into an ``invoke`` of a new, potentially-throwing intrinsic would require adding a 12922large number of intrinsics, impede optimization of those operations, and make 12923compilation slower by introducing many extra basic blocks. These intrinsics can 12924be used instead to mark the region protected by a cleanup, such as for a local 12925C++ object with a non-trivial destructor. ``llvm.seh.scope.begin`` is used to mark 12926the start of the region; it is always called with ``invoke``, with the unwind block 12927being the desired unwind destination for any potentially-throwing instructions 12928within the region. `llvm.seh.scope.end` is used to mark when the scope ends 12929and the EH cleanup is no longer required (e.g. because the destructor is being 12930called). 12931 12932.. _int_read_register: 12933.. _int_read_volatile_register: 12934.. _int_write_register: 12935 12936'``llvm.read_register``', '``llvm.read_volatile_register``', and '``llvm.write_register``' Intrinsics 12937^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12938 12939Syntax: 12940""""""" 12941 12942:: 12943 12944 declare i32 @llvm.read_register.i32(metadata) 12945 declare i64 @llvm.read_register.i64(metadata) 12946 declare i32 @llvm.read_volatile_register.i32(metadata) 12947 declare i64 @llvm.read_volatile_register.i64(metadata) 12948 declare void @llvm.write_register.i32(metadata, i32 @value) 12949 declare void @llvm.write_register.i64(metadata, i64 @value) 12950 !0 = !{!"sp\00"} 12951 12952Overview: 12953""""""""" 12954 12955The '``llvm.read_register``', '``llvm.read_volatile_register``', and 12956'``llvm.write_register``' intrinsics provide access to the named register. 12957The register must be valid on the architecture being compiled to. The type 12958needs to be compatible with the register being read. 12959 12960Semantics: 12961"""""""""" 12962 12963The '``llvm.read_register``' and '``llvm.read_volatile_register``' intrinsics 12964return the current value of the register, where possible. The 12965'``llvm.write_register``' intrinsic sets the current value of the register, 12966where possible. 12967 12968A call to '``llvm.read_volatile_register``' is assumed to have side-effects 12969and possibly return a different value each time (e.g. for a timer register). 12970 12971This is useful to implement named register global variables that need 12972to always be mapped to a specific register, as is common practice on 12973bare-metal programs including OS kernels. 12974 12975The compiler doesn't check for register availability or use of the used 12976register in surrounding code, including inline assembly. Because of that, 12977allocatable registers are not supported. 12978 12979Warning: So far it only works with the stack pointer on selected 12980architectures (ARM, AArch64, PowerPC and x86_64). Significant amount of 12981work is needed to support other registers and even more so, allocatable 12982registers. 12983 12984.. _int_stacksave: 12985 12986'``llvm.stacksave``' Intrinsic 12987^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 12988 12989Syntax: 12990""""""" 12991 12992:: 12993 12994 declare ptr @llvm.stacksave() 12995 12996Overview: 12997""""""""" 12998 12999The '``llvm.stacksave``' intrinsic is used to remember the current state 13000of the function stack, for use with 13001:ref:`llvm.stackrestore <int_stackrestore>`. This is useful for 13002implementing language features like scoped automatic variable sized 13003arrays in C99. 13004 13005Semantics: 13006"""""""""" 13007 13008This intrinsic returns an opaque pointer value that can be passed to 13009:ref:`llvm.stackrestore <int_stackrestore>`. When an 13010``llvm.stackrestore`` intrinsic is executed with a value saved from 13011``llvm.stacksave``, it effectively restores the state of the stack to 13012the state it was in when the ``llvm.stacksave`` intrinsic executed. In 13013practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that 13014were allocated after the ``llvm.stacksave`` was executed. 13015 13016.. _int_stackrestore: 13017 13018'``llvm.stackrestore``' Intrinsic 13019^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13020 13021Syntax: 13022""""""" 13023 13024:: 13025 13026 declare void @llvm.stackrestore(ptr %ptr) 13027 13028Overview: 13029""""""""" 13030 13031The '``llvm.stackrestore``' intrinsic is used to restore the state of 13032the function stack to the state it was in when the corresponding 13033:ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is 13034useful for implementing language features like scoped automatic variable 13035sized arrays in C99. 13036 13037Semantics: 13038"""""""""" 13039 13040See the description for :ref:`llvm.stacksave <int_stacksave>`. 13041 13042.. _int_get_dynamic_area_offset: 13043 13044'``llvm.get.dynamic.area.offset``' Intrinsic 13045^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13046 13047Syntax: 13048""""""" 13049 13050:: 13051 13052 declare i32 @llvm.get.dynamic.area.offset.i32() 13053 declare i64 @llvm.get.dynamic.area.offset.i64() 13054 13055Overview: 13056""""""""" 13057 13058 The '``llvm.get.dynamic.area.offset.*``' intrinsic family is used to 13059 get the offset from native stack pointer to the address of the most 13060 recent dynamic alloca on the caller's stack. These intrinsics are 13061 intended for use in combination with 13062 :ref:`llvm.stacksave <int_stacksave>` to get a 13063 pointer to the most recent dynamic alloca. This is useful, for example, 13064 for AddressSanitizer's stack unpoisoning routines. 13065 13066Semantics: 13067"""""""""" 13068 13069 These intrinsics return a non-negative integer value that can be used to 13070 get the address of the most recent dynamic alloca, allocated by :ref:`alloca <i_alloca>` 13071 on the caller's stack. In particular, for targets where stack grows downwards, 13072 adding this offset to the native stack pointer would get the address of the most 13073 recent dynamic alloca. For targets where stack grows upwards, the situation is a bit more 13074 complicated, because subtracting this value from stack pointer would get the address 13075 one past the end of the most recent dynamic alloca. 13076 13077 Although for most targets `llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>` 13078 returns just a zero, for others, such as PowerPC and PowerPC64, it returns a 13079 compile-time-known constant value. 13080 13081 The return value type of :ref:`llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>` 13082 must match the target's default address space's (address space 0) pointer type. 13083 13084'``llvm.prefetch``' Intrinsic 13085^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13086 13087Syntax: 13088""""""" 13089 13090:: 13091 13092 declare void @llvm.prefetch(ptr <address>, i32 <rw>, i32 <locality>, i32 <cache type>) 13093 13094Overview: 13095""""""""" 13096 13097The '``llvm.prefetch``' intrinsic is a hint to the code generator to 13098insert a prefetch instruction if supported; otherwise, it is a noop. 13099Prefetches have no effect on the behavior of the program but can change 13100its performance characteristics. 13101 13102Arguments: 13103"""""""""" 13104 13105``address`` is the address to be prefetched, ``rw`` is the specifier 13106determining if the fetch should be for a read (0) or write (1), and 13107``locality`` is a temporal locality specifier ranging from (0) - no 13108locality, to (3) - extremely local keep in cache. The ``cache type`` 13109specifies whether the prefetch is performed on the data (1) or 13110instruction (0) cache. The ``rw``, ``locality`` and ``cache type`` 13111arguments must be constant integers. 13112 13113Semantics: 13114"""""""""" 13115 13116This intrinsic does not modify the behavior of the program. In 13117particular, prefetches cannot trap and do not produce a value. On 13118targets that support this intrinsic, the prefetch can provide hints to 13119the processor cache for better performance. 13120 13121'``llvm.pcmarker``' Intrinsic 13122^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13123 13124Syntax: 13125""""""" 13126 13127:: 13128 13129 declare void @llvm.pcmarker(i32 <id>) 13130 13131Overview: 13132""""""""" 13133 13134The '``llvm.pcmarker``' intrinsic is a method to export a Program 13135Counter (PC) in a region of code to simulators and other tools. The 13136method is target specific, but it is expected that the marker will use 13137exported symbols to transmit the PC of the marker. The marker makes no 13138guarantees that it will remain with any specific instruction after 13139optimizations. It is possible that the presence of a marker will inhibit 13140optimizations. The intended use is to be inserted after optimizations to 13141allow correlations of simulation runs. 13142 13143Arguments: 13144"""""""""" 13145 13146``id`` is a numerical id identifying the marker. 13147 13148Semantics: 13149"""""""""" 13150 13151This intrinsic does not modify the behavior of the program. Backends 13152that do not support this intrinsic may ignore it. 13153 13154'``llvm.readcyclecounter``' Intrinsic 13155^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13156 13157Syntax: 13158""""""" 13159 13160:: 13161 13162 declare i64 @llvm.readcyclecounter() 13163 13164Overview: 13165""""""""" 13166 13167The '``llvm.readcyclecounter``' intrinsic provides access to the cycle 13168counter register (or similar low latency, high accuracy clocks) on those 13169targets that support it. On X86, it should map to RDTSC. On Alpha, it 13170should map to RPCC. As the backing counters overflow quickly (on the 13171order of 9 seconds on alpha), this should only be used for small 13172timings. 13173 13174Semantics: 13175"""""""""" 13176 13177When directly supported, reading the cycle counter should not modify any 13178memory. Implementations are allowed to either return an application 13179specific value or a system wide value. On backends without support, this 13180is lowered to a constant 0. 13181 13182Note that runtime support may be conditional on the privilege-level code is 13183running at and the host platform. 13184 13185'``llvm.clear_cache``' Intrinsic 13186^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13187 13188Syntax: 13189""""""" 13190 13191:: 13192 13193 declare void @llvm.clear_cache(ptr, ptr) 13194 13195Overview: 13196""""""""" 13197 13198The '``llvm.clear_cache``' intrinsic ensures visibility of modifications 13199in the specified range to the execution unit of the processor. On 13200targets with non-unified instruction and data cache, the implementation 13201flushes the instruction cache. 13202 13203Semantics: 13204"""""""""" 13205 13206On platforms with coherent instruction and data caches (e.g. x86), this 13207intrinsic is a nop. On platforms with non-coherent instruction and data 13208cache (e.g. ARM, MIPS), the intrinsic is lowered either to appropriate 13209instructions or a system call, if cache flushing requires special 13210privileges. 13211 13212The default behavior is to emit a call to ``__clear_cache`` from the run 13213time library. 13214 13215This intrinsic does *not* empty the instruction pipeline. Modifications 13216of the current function are outside the scope of the intrinsic. 13217 13218'``llvm.instrprof.increment``' Intrinsic 13219^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13220 13221Syntax: 13222""""""" 13223 13224:: 13225 13226 declare void @llvm.instrprof.increment(ptr <name>, i64 <hash>, 13227 i32 <num-counters>, i32 <index>) 13228 13229Overview: 13230""""""""" 13231 13232The '``llvm.instrprof.increment``' intrinsic can be emitted by a 13233frontend for use with instrumentation based profiling. These will be 13234lowered by the ``-instrprof`` pass to generate execution counts of a 13235program at runtime. 13236 13237Arguments: 13238"""""""""" 13239 13240The first argument is a pointer to a global variable containing the 13241name of the entity being instrumented. This should generally be the 13242(mangled) function name for a set of counters. 13243 13244The second argument is a hash value that can be used by the consumer 13245of the profile data to detect changes to the instrumented source, and 13246the third is the number of counters associated with ``name``. It is an 13247error if ``hash`` or ``num-counters`` differ between two instances of 13248``instrprof.increment`` that refer to the same name. 13249 13250The last argument refers to which of the counters for ``name`` should 13251be incremented. It should be a value between 0 and ``num-counters``. 13252 13253Semantics: 13254"""""""""" 13255 13256This intrinsic represents an increment of a profiling counter. It will 13257cause the ``-instrprof`` pass to generate the appropriate data 13258structures and the code to increment the appropriate value, in a 13259format that can be written out by a compiler runtime and consumed via 13260the ``llvm-profdata`` tool. 13261 13262'``llvm.instrprof.increment.step``' Intrinsic 13263^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13264 13265Syntax: 13266""""""" 13267 13268:: 13269 13270 declare void @llvm.instrprof.increment.step(ptr <name>, i64 <hash>, 13271 i32 <num-counters>, 13272 i32 <index>, i64 <step>) 13273 13274Overview: 13275""""""""" 13276 13277The '``llvm.instrprof.increment.step``' intrinsic is an extension to 13278the '``llvm.instrprof.increment``' intrinsic with an additional fifth 13279argument to specify the step of the increment. 13280 13281Arguments: 13282"""""""""" 13283The first four arguments are the same as '``llvm.instrprof.increment``' 13284intrinsic. 13285 13286The last argument specifies the value of the increment of the counter variable. 13287 13288Semantics: 13289"""""""""" 13290See description of '``llvm.instrprof.increment``' intrinsic. 13291 13292'``llvm.instrprof.cover``' Intrinsic 13293^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13294 13295Syntax: 13296""""""" 13297 13298:: 13299 13300 declare void @llvm.instrprof.cover(ptr <name>, i64 <hash>, 13301 i32 <num-counters>, i32 <index>) 13302 13303Overview: 13304""""""""" 13305 13306The '``llvm.instrprof.cover``' intrinsic is used to implement coverage 13307instrumentation. 13308 13309Arguments: 13310"""""""""" 13311The arguments are the same as the first four arguments of 13312'``llvm.instrprof.increment``'. 13313 13314Semantics: 13315"""""""""" 13316Similar to the '``llvm.instrprof.increment``' intrinsic, but it stores zero to 13317the profiling variable to signify that the function has been covered. We store 13318zero because this is more efficient on some targets. 13319 13320'``llvm.instrprof.value.profile``' Intrinsic 13321^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13322 13323Syntax: 13324""""""" 13325 13326:: 13327 13328 declare void @llvm.instrprof.value.profile(ptr <name>, i64 <hash>, 13329 i64 <value>, i32 <value_kind>, 13330 i32 <index>) 13331 13332Overview: 13333""""""""" 13334 13335The '``llvm.instrprof.value.profile``' intrinsic can be emitted by a 13336frontend for use with instrumentation based profiling. This will be 13337lowered by the ``-instrprof`` pass to find out the target values, 13338instrumented expressions take in a program at runtime. 13339 13340Arguments: 13341"""""""""" 13342 13343The first argument is a pointer to a global variable containing the 13344name of the entity being instrumented. ``name`` should generally be the 13345(mangled) function name for a set of counters. 13346 13347The second argument is a hash value that can be used by the consumer 13348of the profile data to detect changes to the instrumented source. It 13349is an error if ``hash`` differs between two instances of 13350``llvm.instrprof.*`` that refer to the same name. 13351 13352The third argument is the value of the expression being profiled. The profiled 13353expression's value should be representable as an unsigned 64-bit value. The 13354fourth argument represents the kind of value profiling that is being done. The 13355supported value profiling kinds are enumerated through the 13356``InstrProfValueKind`` type declared in the 13357``<include/llvm/ProfileData/InstrProf.h>`` header file. The last argument is the 13358index of the instrumented expression within ``name``. It should be >= 0. 13359 13360Semantics: 13361"""""""""" 13362 13363This intrinsic represents the point where a call to a runtime routine 13364should be inserted for value profiling of target expressions. ``-instrprof`` 13365pass will generate the appropriate data structures and replace the 13366``llvm.instrprof.value.profile`` intrinsic with the call to the profile 13367runtime library with proper arguments. 13368 13369'``llvm.thread.pointer``' Intrinsic 13370^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13371 13372Syntax: 13373""""""" 13374 13375:: 13376 13377 declare ptr @llvm.thread.pointer() 13378 13379Overview: 13380""""""""" 13381 13382The '``llvm.thread.pointer``' intrinsic returns the value of the thread 13383pointer. 13384 13385Semantics: 13386"""""""""" 13387 13388The '``llvm.thread.pointer``' intrinsic returns a pointer to the TLS area 13389for the current thread. The exact semantics of this value are target 13390specific: it may point to the start of TLS area, to the end, or somewhere 13391in the middle. Depending on the target, this intrinsic may read a register, 13392call a helper function, read from an alternate memory space, or perform 13393other operations necessary to locate the TLS area. Not all targets support 13394this intrinsic. 13395 13396'``llvm.call.preallocated.setup``' Intrinsic 13397^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13398 13399Syntax: 13400""""""" 13401 13402:: 13403 13404 declare token @llvm.call.preallocated.setup(i32 %num_args) 13405 13406Overview: 13407""""""""" 13408 13409The '``llvm.call.preallocated.setup``' intrinsic returns a token which can 13410be used with a call's ``"preallocated"`` operand bundle to indicate that 13411certain arguments are allocated and initialized before the call. 13412 13413Semantics: 13414"""""""""" 13415 13416The '``llvm.call.preallocated.setup``' intrinsic returns a token which is 13417associated with at most one call. The token can be passed to 13418'``@llvm.call.preallocated.arg``' to get a pointer to get that 13419corresponding argument. The token must be the parameter to a 13420``"preallocated"`` operand bundle for the corresponding call. 13421 13422Nested calls to '``llvm.call.preallocated.setup``' are allowed, but must 13423be properly nested. e.g. 13424 13425:: code-block:: llvm 13426 13427 %t1 = call token @llvm.call.preallocated.setup(i32 0) 13428 %t2 = call token @llvm.call.preallocated.setup(i32 0) 13429 call void foo() ["preallocated"(token %t2)] 13430 call void foo() ["preallocated"(token %t1)] 13431 13432is allowed, but not 13433 13434:: code-block:: llvm 13435 13436 %t1 = call token @llvm.call.preallocated.setup(i32 0) 13437 %t2 = call token @llvm.call.preallocated.setup(i32 0) 13438 call void foo() ["preallocated"(token %t1)] 13439 call void foo() ["preallocated"(token %t2)] 13440 13441.. _int_call_preallocated_arg: 13442 13443'``llvm.call.preallocated.arg``' Intrinsic 13444^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13445 13446Syntax: 13447""""""" 13448 13449:: 13450 13451 declare ptr @llvm.call.preallocated.arg(token %setup_token, i32 %arg_index) 13452 13453Overview: 13454""""""""" 13455 13456The '``llvm.call.preallocated.arg``' intrinsic returns a pointer to the 13457corresponding preallocated argument for the preallocated call. 13458 13459Semantics: 13460"""""""""" 13461 13462The '``llvm.call.preallocated.arg``' intrinsic returns a pointer to the 13463``%arg_index``th argument with the ``preallocated`` attribute for 13464the call associated with the ``%setup_token``, which must be from 13465'``llvm.call.preallocated.setup``'. 13466 13467A call to '``llvm.call.preallocated.arg``' must have a call site 13468``preallocated`` attribute. The type of the ``preallocated`` attribute must 13469match the type used by the ``preallocated`` attribute of the corresponding 13470argument at the preallocated call. The type is used in the case that an 13471``llvm.call.preallocated.setup`` does not have a corresponding call (e.g. due 13472to DCE), where otherwise we cannot know how large the arguments are. 13473 13474It is undefined behavior if this is called with a token from an 13475'``llvm.call.preallocated.setup``' if another 13476'``llvm.call.preallocated.setup``' has already been called or if the 13477preallocated call corresponding to the '``llvm.call.preallocated.setup``' 13478has already been called. 13479 13480.. _int_call_preallocated_teardown: 13481 13482'``llvm.call.preallocated.teardown``' Intrinsic 13483^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13484 13485Syntax: 13486""""""" 13487 13488:: 13489 13490 declare ptr @llvm.call.preallocated.teardown(token %setup_token) 13491 13492Overview: 13493""""""""" 13494 13495The '``llvm.call.preallocated.teardown``' intrinsic cleans up the stack 13496created by a '``llvm.call.preallocated.setup``'. 13497 13498Semantics: 13499"""""""""" 13500 13501The token argument must be a '``llvm.call.preallocated.setup``'. 13502 13503The '``llvm.call.preallocated.teardown``' intrinsic cleans up the stack 13504allocated by the corresponding '``llvm.call.preallocated.setup``'. Exactly 13505one of this or the preallocated call must be called to prevent stack leaks. 13506It is undefined behavior to call both a '``llvm.call.preallocated.teardown``' 13507and the preallocated call for a given '``llvm.call.preallocated.setup``'. 13508 13509For example, if the stack is allocated for a preallocated call by a 13510'``llvm.call.preallocated.setup``', then an initializer function called on an 13511allocated argument throws an exception, there should be a 13512'``llvm.call.preallocated.teardown``' in the exception handler to prevent 13513stack leaks. 13514 13515Following the nesting rules in '``llvm.call.preallocated.setup``', nested 13516calls to '``llvm.call.preallocated.setup``' and 13517'``llvm.call.preallocated.teardown``' are allowed but must be properly 13518nested. 13519 13520Example: 13521"""""""" 13522 13523.. code-block:: llvm 13524 13525 %cs = call token @llvm.call.preallocated.setup(i32 1) 13526 %x = call ptr @llvm.call.preallocated.arg(token %cs, i32 0) preallocated(i32) 13527 invoke void @constructor(ptr %x) to label %conta unwind label %contb 13528 conta: 13529 call void @foo1(ptr preallocated(i32) %x) ["preallocated"(token %cs)] 13530 ret void 13531 contb: 13532 %s = catchswitch within none [label %catch] unwind to caller 13533 catch: 13534 %p = catchpad within %s [] 13535 call void @llvm.call.preallocated.teardown(token %cs) 13536 ret void 13537 13538Standard C/C++ Library Intrinsics 13539--------------------------------- 13540 13541LLVM provides intrinsics for a few important standard C/C++ library 13542functions. These intrinsics allow source-language front-ends to pass 13543information about the alignment of the pointer arguments to the code 13544generator, providing opportunity for more efficient code generation. 13545 13546 13547'``llvm.abs.*``' Intrinsic 13548^^^^^^^^^^^^^^^^^^^^^^^^^^ 13549 13550Syntax: 13551""""""" 13552 13553This is an overloaded intrinsic. You can use ``llvm.abs`` on any 13554integer bit width or any vector of integer elements. 13555 13556:: 13557 13558 declare i32 @llvm.abs.i32(i32 <src>, i1 <is_int_min_poison>) 13559 declare <4 x i32> @llvm.abs.v4i32(<4 x i32> <src>, i1 <is_int_min_poison>) 13560 13561Overview: 13562""""""""" 13563 13564The '``llvm.abs``' family of intrinsic functions returns the absolute value 13565of an argument. 13566 13567Arguments: 13568"""""""""" 13569 13570The first argument is the value for which the absolute value is to be returned. 13571This argument may be of any integer type or a vector with integer element type. 13572The return type must match the first argument type. 13573 13574The second argument must be a constant and is a flag to indicate whether the 13575result value of the '``llvm.abs``' intrinsic is a 13576:ref:`poison value <poisonvalues>` if the argument is statically or dynamically 13577an ``INT_MIN`` value. 13578 13579Semantics: 13580"""""""""" 13581 13582The '``llvm.abs``' intrinsic returns the magnitude (always positive) of the 13583argument or each element of a vector argument.". If the argument is ``INT_MIN``, 13584then the result is also ``INT_MIN`` if ``is_int_min_poison == 0`` and 13585``poison`` otherwise. 13586 13587 13588'``llvm.smax.*``' Intrinsic 13589^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13590 13591Syntax: 13592""""""" 13593 13594This is an overloaded intrinsic. You can use ``@llvm.smax`` on any 13595integer bit width or any vector of integer elements. 13596 13597:: 13598 13599 declare i32 @llvm.smax.i32(i32 %a, i32 %b) 13600 declare <4 x i32> @llvm.smax.v4i32(<4 x i32> %a, <4 x i32> %b) 13601 13602Overview: 13603""""""""" 13604 13605Return the larger of ``%a`` and ``%b`` comparing the values as signed integers. 13606Vector intrinsics operate on a per-element basis. The larger element of ``%a`` 13607and ``%b`` at a given index is returned for that index. 13608 13609Arguments: 13610"""""""""" 13611 13612The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13613integer element type. The argument types must match each other, and the return 13614type must match the argument type. 13615 13616 13617'``llvm.smin.*``' Intrinsic 13618^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13619 13620Syntax: 13621""""""" 13622 13623This is an overloaded intrinsic. You can use ``@llvm.smin`` on any 13624integer bit width or any vector of integer elements. 13625 13626:: 13627 13628 declare i32 @llvm.smin.i32(i32 %a, i32 %b) 13629 declare <4 x i32> @llvm.smin.v4i32(<4 x i32> %a, <4 x i32> %b) 13630 13631Overview: 13632""""""""" 13633 13634Return the smaller of ``%a`` and ``%b`` comparing the values as signed integers. 13635Vector intrinsics operate on a per-element basis. The smaller element of ``%a`` 13636and ``%b`` at a given index is returned for that index. 13637 13638Arguments: 13639"""""""""" 13640 13641The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13642integer element type. The argument types must match each other, and the return 13643type must match the argument type. 13644 13645 13646'``llvm.umax.*``' Intrinsic 13647^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13648 13649Syntax: 13650""""""" 13651 13652This is an overloaded intrinsic. You can use ``@llvm.umax`` on any 13653integer bit width or any vector of integer elements. 13654 13655:: 13656 13657 declare i32 @llvm.umax.i32(i32 %a, i32 %b) 13658 declare <4 x i32> @llvm.umax.v4i32(<4 x i32> %a, <4 x i32> %b) 13659 13660Overview: 13661""""""""" 13662 13663Return the larger of ``%a`` and ``%b`` comparing the values as unsigned 13664integers. Vector intrinsics operate on a per-element basis. The larger element 13665of ``%a`` and ``%b`` at a given index is returned for that index. 13666 13667Arguments: 13668"""""""""" 13669 13670The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13671integer element type. The argument types must match each other, and the return 13672type must match the argument type. 13673 13674 13675'``llvm.umin.*``' Intrinsic 13676^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13677 13678Syntax: 13679""""""" 13680 13681This is an overloaded intrinsic. You can use ``@llvm.umin`` on any 13682integer bit width or any vector of integer elements. 13683 13684:: 13685 13686 declare i32 @llvm.umin.i32(i32 %a, i32 %b) 13687 declare <4 x i32> @llvm.umin.v4i32(<4 x i32> %a, <4 x i32> %b) 13688 13689Overview: 13690""""""""" 13691 13692Return the smaller of ``%a`` and ``%b`` comparing the values as unsigned 13693integers. Vector intrinsics operate on a per-element basis. The smaller element 13694of ``%a`` and ``%b`` at a given index is returned for that index. 13695 13696Arguments: 13697"""""""""" 13698 13699The arguments (``%a`` and ``%b``) may be of any integer type or a vector with 13700integer element type. The argument types must match each other, and the return 13701type must match the argument type. 13702 13703 13704.. _int_memcpy: 13705 13706'``llvm.memcpy``' Intrinsic 13707^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13708 13709Syntax: 13710""""""" 13711 13712This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any 13713integer bit width and for different address spaces. Not all targets 13714support all bit widths however. 13715 13716:: 13717 13718 declare void @llvm.memcpy.p0.p0.i32(ptr <dest>, ptr <src>, 13719 i32 <len>, i1 <isvolatile>) 13720 declare void @llvm.memcpy.p0.p0.i64(ptr <dest>, ptr <src>, 13721 i64 <len>, i1 <isvolatile>) 13722 13723Overview: 13724""""""""" 13725 13726The '``llvm.memcpy.*``' intrinsics copy a block of memory from the 13727source location to the destination location. 13728 13729Note that, unlike the standard libc function, the ``llvm.memcpy.*`` 13730intrinsics do not return a value, takes extra isvolatile 13731arguments and the pointers can be in specified address spaces. 13732 13733Arguments: 13734"""""""""" 13735 13736The first argument is a pointer to the destination, the second is a 13737pointer to the source. The third argument is an integer argument 13738specifying the number of bytes to copy, and the fourth is a 13739boolean indicating a volatile access. 13740 13741The :ref:`align <attr_align>` parameter attribute can be provided 13742for the first and second arguments. 13743 13744If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is 13745a :ref:`volatile operation <volatile>`. The detailed access behavior is not 13746very cleanly specified and it is unwise to depend on it. 13747 13748Semantics: 13749"""""""""" 13750 13751The '``llvm.memcpy.*``' intrinsics copy a block of memory from the source 13752location to the destination location, which must either be equal or 13753non-overlapping. It copies "len" bytes of memory over. If the argument is known 13754to be aligned to some boundary, this can be specified as an attribute on the 13755argument. 13756 13757If ``<len>`` is 0, it is no-op modulo the behavior of attributes attached to 13758the arguments. 13759If ``<len>`` is not a well-defined value, the behavior is undefined. 13760If ``<len>`` is not zero, both ``<dest>`` and ``<src>`` should be well-defined, 13761otherwise the behavior is undefined. 13762 13763.. _int_memcpy_inline: 13764 13765'``llvm.memcpy.inline``' Intrinsic 13766^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13767 13768Syntax: 13769""""""" 13770 13771This is an overloaded intrinsic. You can use ``llvm.memcpy.inline`` on any 13772integer bit width and for different address spaces. Not all targets 13773support all bit widths however. 13774 13775:: 13776 13777 declare void @llvm.memcpy.inline.p0.p0.i32(ptr <dest>, ptr <src>, 13778 i32 <len>, i1 <isvolatile>) 13779 declare void @llvm.memcpy.inline.p0.p0.i64(ptr <dest>, ptr <src>, 13780 i64 <len>, i1 <isvolatile>) 13781 13782Overview: 13783""""""""" 13784 13785The '``llvm.memcpy.inline.*``' intrinsics copy a block of memory from the 13786source location to the destination location and guarantees that no external 13787functions are called. 13788 13789Note that, unlike the standard libc function, the ``llvm.memcpy.inline.*`` 13790intrinsics do not return a value, takes extra isvolatile 13791arguments and the pointers can be in specified address spaces. 13792 13793Arguments: 13794"""""""""" 13795 13796The first argument is a pointer to the destination, the second is a 13797pointer to the source. The third argument is a constant integer argument 13798specifying the number of bytes to copy, and the fourth is a 13799boolean indicating a volatile access. 13800 13801The :ref:`align <attr_align>` parameter attribute can be provided 13802for the first and second arguments. 13803 13804If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy.inline`` call is 13805a :ref:`volatile operation <volatile>`. The detailed access behavior is not 13806very cleanly specified and it is unwise to depend on it. 13807 13808Semantics: 13809"""""""""" 13810 13811The '``llvm.memcpy.inline.*``' intrinsics copy a block of memory from the 13812source location to the destination location, which are not allowed to 13813overlap. It copies "len" bytes of memory over. If the argument is known 13814to be aligned to some boundary, this can be specified as an attribute on 13815the argument. 13816The behavior of '``llvm.memcpy.inline.*``' is equivalent to the behavior of 13817'``llvm.memcpy.*``', but the generated code is guaranteed not to call any 13818external functions. 13819 13820.. _int_memmove: 13821 13822'``llvm.memmove``' Intrinsic 13823^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13824 13825Syntax: 13826""""""" 13827 13828This is an overloaded intrinsic. You can use llvm.memmove on any integer 13829bit width and for different address space. Not all targets support all 13830bit widths however. 13831 13832:: 13833 13834 declare void @llvm.memmove.p0.p0.i32(ptr <dest>, ptr <src>, 13835 i32 <len>, i1 <isvolatile>) 13836 declare void @llvm.memmove.p0.p0.i64(ptr <dest>, ptr <src>, 13837 i64 <len>, i1 <isvolatile>) 13838 13839Overview: 13840""""""""" 13841 13842The '``llvm.memmove.*``' intrinsics move a block of memory from the 13843source location to the destination location. It is similar to the 13844'``llvm.memcpy``' intrinsic but allows the two memory locations to 13845overlap. 13846 13847Note that, unlike the standard libc function, the ``llvm.memmove.*`` 13848intrinsics do not return a value, takes an extra isvolatile 13849argument and the pointers can be in specified address spaces. 13850 13851Arguments: 13852"""""""""" 13853 13854The first argument is a pointer to the destination, the second is a 13855pointer to the source. The third argument is an integer argument 13856specifying the number of bytes to copy, and the fourth is a 13857boolean indicating a volatile access. 13858 13859The :ref:`align <attr_align>` parameter attribute can be provided 13860for the first and second arguments. 13861 13862If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call 13863is a :ref:`volatile operation <volatile>`. The detailed access behavior is 13864not very cleanly specified and it is unwise to depend on it. 13865 13866Semantics: 13867"""""""""" 13868 13869The '``llvm.memmove.*``' intrinsics copy a block of memory from the 13870source location to the destination location, which may overlap. It 13871copies "len" bytes of memory over. If the argument is known to be 13872aligned to some boundary, this can be specified as an attribute on 13873the argument. 13874 13875If ``<len>`` is 0, it is no-op modulo the behavior of attributes attached to 13876the arguments. 13877If ``<len>`` is not a well-defined value, the behavior is undefined. 13878If ``<len>`` is not zero, both ``<dest>`` and ``<src>`` should be well-defined, 13879otherwise the behavior is undefined. 13880 13881.. _int_memset: 13882 13883'``llvm.memset.*``' Intrinsics 13884^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13885 13886Syntax: 13887""""""" 13888 13889This is an overloaded intrinsic. You can use llvm.memset on any integer 13890bit width and for different address spaces. However, not all targets 13891support all bit widths. 13892 13893:: 13894 13895 declare void @llvm.memset.p0.i32(ptr <dest>, i8 <val>, 13896 i32 <len>, i1 <isvolatile>) 13897 declare void @llvm.memset.p0.i64(ptr <dest>, i8 <val>, 13898 i64 <len>, i1 <isvolatile>) 13899 13900Overview: 13901""""""""" 13902 13903The '``llvm.memset.*``' intrinsics fill a block of memory with a 13904particular byte value. 13905 13906Note that, unlike the standard libc function, the ``llvm.memset`` 13907intrinsic does not return a value and takes an extra volatile 13908argument. Also, the destination can be in an arbitrary address space. 13909 13910Arguments: 13911"""""""""" 13912 13913The first argument is a pointer to the destination to fill, the second 13914is the byte value with which to fill it, the third argument is an 13915integer argument specifying the number of bytes to fill, and the fourth 13916is a boolean indicating a volatile access. 13917 13918The :ref:`align <attr_align>` parameter attribute can be provided 13919for the first arguments. 13920 13921If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is 13922a :ref:`volatile operation <volatile>`. The detailed access behavior is not 13923very cleanly specified and it is unwise to depend on it. 13924 13925Semantics: 13926"""""""""" 13927 13928The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting 13929at the destination location. If the argument is known to be 13930aligned to some boundary, this can be specified as an attribute on 13931the argument. 13932 13933If ``<len>`` is 0, it is no-op modulo the behavior of attributes attached to 13934the arguments. 13935If ``<len>`` is not a well-defined value, the behavior is undefined. 13936If ``<len>`` is not zero, ``<dest>`` should be well-defined, otherwise the 13937behavior is undefined. 13938 13939.. _int_memset_inline: 13940 13941'``llvm.memset.inline``' Intrinsic 13942^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 13943 13944Syntax: 13945""""""" 13946 13947This is an overloaded intrinsic. You can use ``llvm.memset.inline`` on any 13948integer bit width and for different address spaces. Not all targets 13949support all bit widths however. 13950 13951:: 13952 13953 declare void @llvm.memset.inline.p0.p0i8.i32(ptr <dest>, i8 <val>, 13954 i32 <len>, i1 <isvolatile>) 13955 declare void @llvm.memset.inline.p0.p0.i64(ptr <dest>, i8 <val>, 13956 i64 <len>, i1 <isvolatile>) 13957 13958Overview: 13959""""""""" 13960 13961The '``llvm.memset.inline.*``' intrinsics fill a block of memory with a 13962particular byte value and guarantees that no external functions are called. 13963 13964Note that, unlike the standard libc function, the ``llvm.memset.inline.*`` 13965intrinsics do not return a value, take an extra isvolatile argument and the 13966pointer can be in specified address spaces. 13967 13968Arguments: 13969"""""""""" 13970 13971The first argument is a pointer to the destination to fill, the second 13972is the byte value with which to fill it, the third argument is a constant 13973integer argument specifying the number of bytes to fill, and the fourth 13974is a boolean indicating a volatile access. 13975 13976The :ref:`align <attr_align>` parameter attribute can be provided 13977for the first argument. 13978 13979If the ``isvolatile`` parameter is ``true``, the ``llvm.memset.inline`` call is 13980a :ref:`volatile operation <volatile>`. The detailed access behavior is not 13981very cleanly specified and it is unwise to depend on it. 13982 13983Semantics: 13984"""""""""" 13985 13986The '``llvm.memset.inline.*``' intrinsics fill "len" bytes of memory starting 13987at the destination location. If the argument is known to be 13988aligned to some boundary, this can be specified as an attribute on 13989the argument. 13990 13991``len`` must be a constant expression. 13992If ``<len>`` is 0, it is no-op modulo the behavior of attributes attached to 13993the arguments. 13994If ``<len>`` is not a well-defined value, the behavior is undefined. 13995If ``<len>`` is not zero, ``<dest>`` should be well-defined, otherwise the 13996behavior is undefined. 13997 13998The behavior of '``llvm.memset.inline.*``' is equivalent to the behavior of 13999'``llvm.memset.*``', but the generated code is guaranteed not to call any 14000external functions. 14001 14002'``llvm.sqrt.*``' Intrinsic 14003^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14004 14005Syntax: 14006""""""" 14007 14008This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any 14009floating-point or vector of floating-point type. Not all targets support 14010all types however. 14011 14012:: 14013 14014 declare float @llvm.sqrt.f32(float %Val) 14015 declare double @llvm.sqrt.f64(double %Val) 14016 declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val) 14017 declare fp128 @llvm.sqrt.f128(fp128 %Val) 14018 declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val) 14019 14020Overview: 14021""""""""" 14022 14023The '``llvm.sqrt``' intrinsics return the square root of the specified value. 14024 14025Arguments: 14026"""""""""" 14027 14028The argument and return value are floating-point numbers of the same type. 14029 14030Semantics: 14031"""""""""" 14032 14033Return the same value as a corresponding libm '``sqrt``' function but without 14034trapping or setting ``errno``. For types specified by IEEE-754, the result 14035matches a conforming libm implementation. 14036 14037When specified with the fast-math-flag 'afn', the result may be approximated 14038using a less accurate calculation. 14039 14040'``llvm.powi.*``' Intrinsic 14041^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14042 14043Syntax: 14044""""""" 14045 14046This is an overloaded intrinsic. You can use ``llvm.powi`` on any 14047floating-point or vector of floating-point type. Not all targets support 14048all types however. 14049 14050Generally, the only supported type for the exponent is the one matching 14051with the C type ``int``. 14052 14053:: 14054 14055 declare float @llvm.powi.f32.i32(float %Val, i32 %power) 14056 declare double @llvm.powi.f64.i16(double %Val, i16 %power) 14057 declare x86_fp80 @llvm.powi.f80.i32(x86_fp80 %Val, i32 %power) 14058 declare fp128 @llvm.powi.f128.i32(fp128 %Val, i32 %power) 14059 declare ppc_fp128 @llvm.powi.ppcf128.i32(ppc_fp128 %Val, i32 %power) 14060 14061Overview: 14062""""""""" 14063 14064The '``llvm.powi.*``' intrinsics return the first operand raised to the 14065specified (positive or negative) power. The order of evaluation of 14066multiplications is not defined. When a vector of floating-point type is 14067used, the second argument remains a scalar integer value. 14068 14069Arguments: 14070"""""""""" 14071 14072The second argument is an integer power, and the first is a value to 14073raise to that power. 14074 14075Semantics: 14076"""""""""" 14077 14078This function returns the first value raised to the second power with an 14079unspecified sequence of rounding operations. 14080 14081'``llvm.sin.*``' Intrinsic 14082^^^^^^^^^^^^^^^^^^^^^^^^^^ 14083 14084Syntax: 14085""""""" 14086 14087This is an overloaded intrinsic. You can use ``llvm.sin`` on any 14088floating-point or vector of floating-point type. Not all targets support 14089all types however. 14090 14091:: 14092 14093 declare float @llvm.sin.f32(float %Val) 14094 declare double @llvm.sin.f64(double %Val) 14095 declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val) 14096 declare fp128 @llvm.sin.f128(fp128 %Val) 14097 declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val) 14098 14099Overview: 14100""""""""" 14101 14102The '``llvm.sin.*``' intrinsics return the sine of the operand. 14103 14104Arguments: 14105"""""""""" 14106 14107The argument and return value are floating-point numbers of the same type. 14108 14109Semantics: 14110"""""""""" 14111 14112Return the same value as a corresponding libm '``sin``' function but without 14113trapping or setting ``errno``. 14114 14115When specified with the fast-math-flag 'afn', the result may be approximated 14116using a less accurate calculation. 14117 14118'``llvm.cos.*``' Intrinsic 14119^^^^^^^^^^^^^^^^^^^^^^^^^^ 14120 14121Syntax: 14122""""""" 14123 14124This is an overloaded intrinsic. You can use ``llvm.cos`` on any 14125floating-point or vector of floating-point type. Not all targets support 14126all types however. 14127 14128:: 14129 14130 declare float @llvm.cos.f32(float %Val) 14131 declare double @llvm.cos.f64(double %Val) 14132 declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val) 14133 declare fp128 @llvm.cos.f128(fp128 %Val) 14134 declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val) 14135 14136Overview: 14137""""""""" 14138 14139The '``llvm.cos.*``' intrinsics return the cosine of the operand. 14140 14141Arguments: 14142"""""""""" 14143 14144The argument and return value are floating-point numbers of the same type. 14145 14146Semantics: 14147"""""""""" 14148 14149Return the same value as a corresponding libm '``cos``' function but without 14150trapping or setting ``errno``. 14151 14152When specified with the fast-math-flag 'afn', the result may be approximated 14153using a less accurate calculation. 14154 14155'``llvm.pow.*``' Intrinsic 14156^^^^^^^^^^^^^^^^^^^^^^^^^^ 14157 14158Syntax: 14159""""""" 14160 14161This is an overloaded intrinsic. You can use ``llvm.pow`` on any 14162floating-point or vector of floating-point type. Not all targets support 14163all types however. 14164 14165:: 14166 14167 declare float @llvm.pow.f32(float %Val, float %Power) 14168 declare double @llvm.pow.f64(double %Val, double %Power) 14169 declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power) 14170 declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power) 14171 declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power) 14172 14173Overview: 14174""""""""" 14175 14176The '``llvm.pow.*``' intrinsics return the first operand raised to the 14177specified (positive or negative) power. 14178 14179Arguments: 14180"""""""""" 14181 14182The arguments and return value are floating-point numbers of the same type. 14183 14184Semantics: 14185"""""""""" 14186 14187Return the same value as a corresponding libm '``pow``' function but without 14188trapping or setting ``errno``. 14189 14190When specified with the fast-math-flag 'afn', the result may be approximated 14191using a less accurate calculation. 14192 14193'``llvm.exp.*``' Intrinsic 14194^^^^^^^^^^^^^^^^^^^^^^^^^^ 14195 14196Syntax: 14197""""""" 14198 14199This is an overloaded intrinsic. You can use ``llvm.exp`` on any 14200floating-point or vector of floating-point type. Not all targets support 14201all types however. 14202 14203:: 14204 14205 declare float @llvm.exp.f32(float %Val) 14206 declare double @llvm.exp.f64(double %Val) 14207 declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val) 14208 declare fp128 @llvm.exp.f128(fp128 %Val) 14209 declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val) 14210 14211Overview: 14212""""""""" 14213 14214The '``llvm.exp.*``' intrinsics compute the base-e exponential of the specified 14215value. 14216 14217Arguments: 14218"""""""""" 14219 14220The argument and return value are floating-point numbers of the same type. 14221 14222Semantics: 14223"""""""""" 14224 14225Return the same value as a corresponding libm '``exp``' function but without 14226trapping or setting ``errno``. 14227 14228When specified with the fast-math-flag 'afn', the result may be approximated 14229using a less accurate calculation. 14230 14231'``llvm.exp2.*``' Intrinsic 14232^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14233 14234Syntax: 14235""""""" 14236 14237This is an overloaded intrinsic. You can use ``llvm.exp2`` on any 14238floating-point or vector of floating-point type. Not all targets support 14239all types however. 14240 14241:: 14242 14243 declare float @llvm.exp2.f32(float %Val) 14244 declare double @llvm.exp2.f64(double %Val) 14245 declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val) 14246 declare fp128 @llvm.exp2.f128(fp128 %Val) 14247 declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val) 14248 14249Overview: 14250""""""""" 14251 14252The '``llvm.exp2.*``' intrinsics compute the base-2 exponential of the 14253specified value. 14254 14255Arguments: 14256"""""""""" 14257 14258The argument and return value are floating-point numbers of the same type. 14259 14260Semantics: 14261"""""""""" 14262 14263Return the same value as a corresponding libm '``exp2``' function but without 14264trapping or setting ``errno``. 14265 14266When specified with the fast-math-flag 'afn', the result may be approximated 14267using a less accurate calculation. 14268 14269'``llvm.log.*``' Intrinsic 14270^^^^^^^^^^^^^^^^^^^^^^^^^^ 14271 14272Syntax: 14273""""""" 14274 14275This is an overloaded intrinsic. You can use ``llvm.log`` on any 14276floating-point or vector of floating-point type. Not all targets support 14277all types however. 14278 14279:: 14280 14281 declare float @llvm.log.f32(float %Val) 14282 declare double @llvm.log.f64(double %Val) 14283 declare x86_fp80 @llvm.log.f80(x86_fp80 %Val) 14284 declare fp128 @llvm.log.f128(fp128 %Val) 14285 declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val) 14286 14287Overview: 14288""""""""" 14289 14290The '``llvm.log.*``' intrinsics compute the base-e logarithm of the specified 14291value. 14292 14293Arguments: 14294"""""""""" 14295 14296The argument and return value are floating-point numbers of the same type. 14297 14298Semantics: 14299"""""""""" 14300 14301Return the same value as a corresponding libm '``log``' function but without 14302trapping or setting ``errno``. 14303 14304When specified with the fast-math-flag 'afn', the result may be approximated 14305using a less accurate calculation. 14306 14307'``llvm.log10.*``' Intrinsic 14308^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14309 14310Syntax: 14311""""""" 14312 14313This is an overloaded intrinsic. You can use ``llvm.log10`` on any 14314floating-point or vector of floating-point type. Not all targets support 14315all types however. 14316 14317:: 14318 14319 declare float @llvm.log10.f32(float %Val) 14320 declare double @llvm.log10.f64(double %Val) 14321 declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val) 14322 declare fp128 @llvm.log10.f128(fp128 %Val) 14323 declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val) 14324 14325Overview: 14326""""""""" 14327 14328The '``llvm.log10.*``' intrinsics compute the base-10 logarithm of the 14329specified value. 14330 14331Arguments: 14332"""""""""" 14333 14334The argument and return value are floating-point numbers of the same type. 14335 14336Semantics: 14337"""""""""" 14338 14339Return the same value as a corresponding libm '``log10``' function but without 14340trapping or setting ``errno``. 14341 14342When specified with the fast-math-flag 'afn', the result may be approximated 14343using a less accurate calculation. 14344 14345'``llvm.log2.*``' Intrinsic 14346^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14347 14348Syntax: 14349""""""" 14350 14351This is an overloaded intrinsic. You can use ``llvm.log2`` on any 14352floating-point or vector of floating-point type. Not all targets support 14353all types however. 14354 14355:: 14356 14357 declare float @llvm.log2.f32(float %Val) 14358 declare double @llvm.log2.f64(double %Val) 14359 declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val) 14360 declare fp128 @llvm.log2.f128(fp128 %Val) 14361 declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val) 14362 14363Overview: 14364""""""""" 14365 14366The '``llvm.log2.*``' intrinsics compute the base-2 logarithm of the specified 14367value. 14368 14369Arguments: 14370"""""""""" 14371 14372The argument and return value are floating-point numbers of the same type. 14373 14374Semantics: 14375"""""""""" 14376 14377Return the same value as a corresponding libm '``log2``' function but without 14378trapping or setting ``errno``. 14379 14380When specified with the fast-math-flag 'afn', the result may be approximated 14381using a less accurate calculation. 14382 14383.. _int_fma: 14384 14385'``llvm.fma.*``' Intrinsic 14386^^^^^^^^^^^^^^^^^^^^^^^^^^ 14387 14388Syntax: 14389""""""" 14390 14391This is an overloaded intrinsic. You can use ``llvm.fma`` on any 14392floating-point or vector of floating-point type. Not all targets support 14393all types however. 14394 14395:: 14396 14397 declare float @llvm.fma.f32(float %a, float %b, float %c) 14398 declare double @llvm.fma.f64(double %a, double %b, double %c) 14399 declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c) 14400 declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c) 14401 declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c) 14402 14403Overview: 14404""""""""" 14405 14406The '``llvm.fma.*``' intrinsics perform the fused multiply-add operation. 14407 14408Arguments: 14409"""""""""" 14410 14411The arguments and return value are floating-point numbers of the same type. 14412 14413Semantics: 14414"""""""""" 14415 14416Return the same value as a corresponding libm '``fma``' function but without 14417trapping or setting ``errno``. 14418 14419When specified with the fast-math-flag 'afn', the result may be approximated 14420using a less accurate calculation. 14421 14422'``llvm.fabs.*``' Intrinsic 14423^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14424 14425Syntax: 14426""""""" 14427 14428This is an overloaded intrinsic. You can use ``llvm.fabs`` on any 14429floating-point or vector of floating-point type. Not all targets support 14430all types however. 14431 14432:: 14433 14434 declare float @llvm.fabs.f32(float %Val) 14435 declare double @llvm.fabs.f64(double %Val) 14436 declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val) 14437 declare fp128 @llvm.fabs.f128(fp128 %Val) 14438 declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val) 14439 14440Overview: 14441""""""""" 14442 14443The '``llvm.fabs.*``' intrinsics return the absolute value of the 14444operand. 14445 14446Arguments: 14447"""""""""" 14448 14449The argument and return value are floating-point numbers of the same 14450type. 14451 14452Semantics: 14453"""""""""" 14454 14455This function returns the same values as the libm ``fabs`` functions 14456would, and handles error conditions in the same way. 14457 14458'``llvm.minnum.*``' Intrinsic 14459^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14460 14461Syntax: 14462""""""" 14463 14464This is an overloaded intrinsic. You can use ``llvm.minnum`` on any 14465floating-point or vector of floating-point type. Not all targets support 14466all types however. 14467 14468:: 14469 14470 declare float @llvm.minnum.f32(float %Val0, float %Val1) 14471 declare double @llvm.minnum.f64(double %Val0, double %Val1) 14472 declare x86_fp80 @llvm.minnum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 14473 declare fp128 @llvm.minnum.f128(fp128 %Val0, fp128 %Val1) 14474 declare ppc_fp128 @llvm.minnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 14475 14476Overview: 14477""""""""" 14478 14479The '``llvm.minnum.*``' intrinsics return the minimum of the two 14480arguments. 14481 14482 14483Arguments: 14484"""""""""" 14485 14486The arguments and return value are floating-point numbers of the same 14487type. 14488 14489Semantics: 14490"""""""""" 14491 14492Follows the IEEE-754 semantics for minNum, except for handling of 14493signaling NaNs. This match's the behavior of libm's fmin. 14494 14495If either operand is a NaN, returns the other non-NaN operand. Returns 14496NaN only if both operands are NaN. The returned NaN is always 14497quiet. If the operands compare equal, returns a value that compares 14498equal to both operands. This means that fmin(+/-0.0, +/-0.0) could 14499return either -0.0 or 0.0. 14500 14501Unlike the IEEE-754 2008 behavior, this does not distinguish between 14502signaling and quiet NaN inputs. If a target's implementation follows 14503the standard and returns a quiet NaN if either input is a signaling 14504NaN, the intrinsic lowering is responsible for quieting the inputs to 14505correctly return the non-NaN input (e.g. by using the equivalent of 14506``llvm.canonicalize``). 14507 14508 14509'``llvm.maxnum.*``' Intrinsic 14510^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14511 14512Syntax: 14513""""""" 14514 14515This is an overloaded intrinsic. You can use ``llvm.maxnum`` on any 14516floating-point or vector of floating-point type. Not all targets support 14517all types however. 14518 14519:: 14520 14521 declare float @llvm.maxnum.f32(float %Val0, float %Val1) 14522 declare double @llvm.maxnum.f64(double %Val0, double %Val1) 14523 declare x86_fp80 @llvm.maxnum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 14524 declare fp128 @llvm.maxnum.f128(fp128 %Val0, fp128 %Val1) 14525 declare ppc_fp128 @llvm.maxnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 14526 14527Overview: 14528""""""""" 14529 14530The '``llvm.maxnum.*``' intrinsics return the maximum of the two 14531arguments. 14532 14533 14534Arguments: 14535"""""""""" 14536 14537The arguments and return value are floating-point numbers of the same 14538type. 14539 14540Semantics: 14541"""""""""" 14542Follows the IEEE-754 semantics for maxNum except for the handling of 14543signaling NaNs. This matches the behavior of libm's fmax. 14544 14545If either operand is a NaN, returns the other non-NaN operand. Returns 14546NaN only if both operands are NaN. The returned NaN is always 14547quiet. If the operands compare equal, returns a value that compares 14548equal to both operands. This means that fmax(+/-0.0, +/-0.0) could 14549return either -0.0 or 0.0. 14550 14551Unlike the IEEE-754 2008 behavior, this does not distinguish between 14552signaling and quiet NaN inputs. If a target's implementation follows 14553the standard and returns a quiet NaN if either input is a signaling 14554NaN, the intrinsic lowering is responsible for quieting the inputs to 14555correctly return the non-NaN input (e.g. by using the equivalent of 14556``llvm.canonicalize``). 14557 14558'``llvm.minimum.*``' Intrinsic 14559^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14560 14561Syntax: 14562""""""" 14563 14564This is an overloaded intrinsic. You can use ``llvm.minimum`` on any 14565floating-point or vector of floating-point type. Not all targets support 14566all types however. 14567 14568:: 14569 14570 declare float @llvm.minimum.f32(float %Val0, float %Val1) 14571 declare double @llvm.minimum.f64(double %Val0, double %Val1) 14572 declare x86_fp80 @llvm.minimum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 14573 declare fp128 @llvm.minimum.f128(fp128 %Val0, fp128 %Val1) 14574 declare ppc_fp128 @llvm.minimum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 14575 14576Overview: 14577""""""""" 14578 14579The '``llvm.minimum.*``' intrinsics return the minimum of the two 14580arguments, propagating NaNs and treating -0.0 as less than +0.0. 14581 14582 14583Arguments: 14584"""""""""" 14585 14586The arguments and return value are floating-point numbers of the same 14587type. 14588 14589Semantics: 14590"""""""""" 14591If either operand is a NaN, returns NaN. Otherwise returns the lesser 14592of the two arguments. -0.0 is considered to be less than +0.0 for this 14593intrinsic. Note that these are the semantics specified in the draft of 14594IEEE 754-2018. 14595 14596'``llvm.maximum.*``' Intrinsic 14597^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14598 14599Syntax: 14600""""""" 14601 14602This is an overloaded intrinsic. You can use ``llvm.maximum`` on any 14603floating-point or vector of floating-point type. Not all targets support 14604all types however. 14605 14606:: 14607 14608 declare float @llvm.maximum.f32(float %Val0, float %Val1) 14609 declare double @llvm.maximum.f64(double %Val0, double %Val1) 14610 declare x86_fp80 @llvm.maximum.f80(x86_fp80 %Val0, x86_fp80 %Val1) 14611 declare fp128 @llvm.maximum.f128(fp128 %Val0, fp128 %Val1) 14612 declare ppc_fp128 @llvm.maximum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1) 14613 14614Overview: 14615""""""""" 14616 14617The '``llvm.maximum.*``' intrinsics return the maximum of the two 14618arguments, propagating NaNs and treating -0.0 as less than +0.0. 14619 14620 14621Arguments: 14622"""""""""" 14623 14624The arguments and return value are floating-point numbers of the same 14625type. 14626 14627Semantics: 14628"""""""""" 14629If either operand is a NaN, returns NaN. Otherwise returns the greater 14630of the two arguments. -0.0 is considered to be less than +0.0 for this 14631intrinsic. Note that these are the semantics specified in the draft of 14632IEEE 754-2018. 14633 14634'``llvm.copysign.*``' Intrinsic 14635^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14636 14637Syntax: 14638""""""" 14639 14640This is an overloaded intrinsic. You can use ``llvm.copysign`` on any 14641floating-point or vector of floating-point type. Not all targets support 14642all types however. 14643 14644:: 14645 14646 declare float @llvm.copysign.f32(float %Mag, float %Sgn) 14647 declare double @llvm.copysign.f64(double %Mag, double %Sgn) 14648 declare x86_fp80 @llvm.copysign.f80(x86_fp80 %Mag, x86_fp80 %Sgn) 14649 declare fp128 @llvm.copysign.f128(fp128 %Mag, fp128 %Sgn) 14650 declare ppc_fp128 @llvm.copysign.ppcf128(ppc_fp128 %Mag, ppc_fp128 %Sgn) 14651 14652Overview: 14653""""""""" 14654 14655The '``llvm.copysign.*``' intrinsics return a value with the magnitude of the 14656first operand and the sign of the second operand. 14657 14658Arguments: 14659"""""""""" 14660 14661The arguments and return value are floating-point numbers of the same 14662type. 14663 14664Semantics: 14665"""""""""" 14666 14667This function returns the same values as the libm ``copysign`` 14668functions would, and handles error conditions in the same way. 14669 14670'``llvm.floor.*``' Intrinsic 14671^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14672 14673Syntax: 14674""""""" 14675 14676This is an overloaded intrinsic. You can use ``llvm.floor`` on any 14677floating-point or vector of floating-point type. Not all targets support 14678all types however. 14679 14680:: 14681 14682 declare float @llvm.floor.f32(float %Val) 14683 declare double @llvm.floor.f64(double %Val) 14684 declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val) 14685 declare fp128 @llvm.floor.f128(fp128 %Val) 14686 declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val) 14687 14688Overview: 14689""""""""" 14690 14691The '``llvm.floor.*``' intrinsics return the floor of the operand. 14692 14693Arguments: 14694"""""""""" 14695 14696The argument and return value are floating-point numbers of the same 14697type. 14698 14699Semantics: 14700"""""""""" 14701 14702This function returns the same values as the libm ``floor`` functions 14703would, and handles error conditions in the same way. 14704 14705'``llvm.ceil.*``' Intrinsic 14706^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14707 14708Syntax: 14709""""""" 14710 14711This is an overloaded intrinsic. You can use ``llvm.ceil`` on any 14712floating-point or vector of floating-point type. Not all targets support 14713all types however. 14714 14715:: 14716 14717 declare float @llvm.ceil.f32(float %Val) 14718 declare double @llvm.ceil.f64(double %Val) 14719 declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val) 14720 declare fp128 @llvm.ceil.f128(fp128 %Val) 14721 declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val) 14722 14723Overview: 14724""""""""" 14725 14726The '``llvm.ceil.*``' intrinsics return the ceiling of the operand. 14727 14728Arguments: 14729"""""""""" 14730 14731The argument and return value are floating-point numbers of the same 14732type. 14733 14734Semantics: 14735"""""""""" 14736 14737This function returns the same values as the libm ``ceil`` functions 14738would, and handles error conditions in the same way. 14739 14740'``llvm.trunc.*``' Intrinsic 14741^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14742 14743Syntax: 14744""""""" 14745 14746This is an overloaded intrinsic. You can use ``llvm.trunc`` on any 14747floating-point or vector of floating-point type. Not all targets support 14748all types however. 14749 14750:: 14751 14752 declare float @llvm.trunc.f32(float %Val) 14753 declare double @llvm.trunc.f64(double %Val) 14754 declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val) 14755 declare fp128 @llvm.trunc.f128(fp128 %Val) 14756 declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val) 14757 14758Overview: 14759""""""""" 14760 14761The '``llvm.trunc.*``' intrinsics returns the operand rounded to the 14762nearest integer not larger in magnitude than the operand. 14763 14764Arguments: 14765"""""""""" 14766 14767The argument and return value are floating-point numbers of the same 14768type. 14769 14770Semantics: 14771"""""""""" 14772 14773This function returns the same values as the libm ``trunc`` functions 14774would, and handles error conditions in the same way. 14775 14776'``llvm.rint.*``' Intrinsic 14777^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14778 14779Syntax: 14780""""""" 14781 14782This is an overloaded intrinsic. You can use ``llvm.rint`` on any 14783floating-point or vector of floating-point type. Not all targets support 14784all types however. 14785 14786:: 14787 14788 declare float @llvm.rint.f32(float %Val) 14789 declare double @llvm.rint.f64(double %Val) 14790 declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val) 14791 declare fp128 @llvm.rint.f128(fp128 %Val) 14792 declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val) 14793 14794Overview: 14795""""""""" 14796 14797The '``llvm.rint.*``' intrinsics returns the operand rounded to the 14798nearest integer. It may raise an inexact floating-point exception if the 14799operand isn't an integer. 14800 14801Arguments: 14802"""""""""" 14803 14804The argument and return value are floating-point numbers of the same 14805type. 14806 14807Semantics: 14808"""""""""" 14809 14810This function returns the same values as the libm ``rint`` functions 14811would, and handles error conditions in the same way. 14812 14813'``llvm.nearbyint.*``' Intrinsic 14814^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14815 14816Syntax: 14817""""""" 14818 14819This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any 14820floating-point or vector of floating-point type. Not all targets support 14821all types however. 14822 14823:: 14824 14825 declare float @llvm.nearbyint.f32(float %Val) 14826 declare double @llvm.nearbyint.f64(double %Val) 14827 declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val) 14828 declare fp128 @llvm.nearbyint.f128(fp128 %Val) 14829 declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val) 14830 14831Overview: 14832""""""""" 14833 14834The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the 14835nearest integer. 14836 14837Arguments: 14838"""""""""" 14839 14840The argument and return value are floating-point numbers of the same 14841type. 14842 14843Semantics: 14844"""""""""" 14845 14846This function returns the same values as the libm ``nearbyint`` 14847functions would, and handles error conditions in the same way. 14848 14849'``llvm.round.*``' Intrinsic 14850^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14851 14852Syntax: 14853""""""" 14854 14855This is an overloaded intrinsic. You can use ``llvm.round`` on any 14856floating-point or vector of floating-point type. Not all targets support 14857all types however. 14858 14859:: 14860 14861 declare float @llvm.round.f32(float %Val) 14862 declare double @llvm.round.f64(double %Val) 14863 declare x86_fp80 @llvm.round.f80(x86_fp80 %Val) 14864 declare fp128 @llvm.round.f128(fp128 %Val) 14865 declare ppc_fp128 @llvm.round.ppcf128(ppc_fp128 %Val) 14866 14867Overview: 14868""""""""" 14869 14870The '``llvm.round.*``' intrinsics returns the operand rounded to the 14871nearest integer. 14872 14873Arguments: 14874"""""""""" 14875 14876The argument and return value are floating-point numbers of the same 14877type. 14878 14879Semantics: 14880"""""""""" 14881 14882This function returns the same values as the libm ``round`` 14883functions would, and handles error conditions in the same way. 14884 14885'``llvm.roundeven.*``' Intrinsic 14886^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14887 14888Syntax: 14889""""""" 14890 14891This is an overloaded intrinsic. You can use ``llvm.roundeven`` on any 14892floating-point or vector of floating-point type. Not all targets support 14893all types however. 14894 14895:: 14896 14897 declare float @llvm.roundeven.f32(float %Val) 14898 declare double @llvm.roundeven.f64(double %Val) 14899 declare x86_fp80 @llvm.roundeven.f80(x86_fp80 %Val) 14900 declare fp128 @llvm.roundeven.f128(fp128 %Val) 14901 declare ppc_fp128 @llvm.roundeven.ppcf128(ppc_fp128 %Val) 14902 14903Overview: 14904""""""""" 14905 14906The '``llvm.roundeven.*``' intrinsics returns the operand rounded to the nearest 14907integer in floating-point format rounding halfway cases to even (that is, to the 14908nearest value that is an even integer). 14909 14910Arguments: 14911"""""""""" 14912 14913The argument and return value are floating-point numbers of the same type. 14914 14915Semantics: 14916"""""""""" 14917 14918This function implements IEEE-754 operation ``roundToIntegralTiesToEven``. It 14919also behaves in the same way as C standard function ``roundeven``, except that 14920it does not raise floating point exceptions. 14921 14922 14923'``llvm.lround.*``' Intrinsic 14924^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14925 14926Syntax: 14927""""""" 14928 14929This is an overloaded intrinsic. You can use ``llvm.lround`` on any 14930floating-point type. Not all targets support all types however. 14931 14932:: 14933 14934 declare i32 @llvm.lround.i32.f32(float %Val) 14935 declare i32 @llvm.lround.i32.f64(double %Val) 14936 declare i32 @llvm.lround.i32.f80(float %Val) 14937 declare i32 @llvm.lround.i32.f128(double %Val) 14938 declare i32 @llvm.lround.i32.ppcf128(double %Val) 14939 14940 declare i64 @llvm.lround.i64.f32(float %Val) 14941 declare i64 @llvm.lround.i64.f64(double %Val) 14942 declare i64 @llvm.lround.i64.f80(float %Val) 14943 declare i64 @llvm.lround.i64.f128(double %Val) 14944 declare i64 @llvm.lround.i64.ppcf128(double %Val) 14945 14946Overview: 14947""""""""" 14948 14949The '``llvm.lround.*``' intrinsics return the operand rounded to the nearest 14950integer with ties away from zero. 14951 14952 14953Arguments: 14954"""""""""" 14955 14956The argument is a floating-point number and the return value is an integer 14957type. 14958 14959Semantics: 14960"""""""""" 14961 14962This function returns the same values as the libm ``lround`` 14963functions would, but without setting errno. 14964 14965'``llvm.llround.*``' Intrinsic 14966^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14967 14968Syntax: 14969""""""" 14970 14971This is an overloaded intrinsic. You can use ``llvm.llround`` on any 14972floating-point type. Not all targets support all types however. 14973 14974:: 14975 14976 declare i64 @llvm.lround.i64.f32(float %Val) 14977 declare i64 @llvm.lround.i64.f64(double %Val) 14978 declare i64 @llvm.lround.i64.f80(float %Val) 14979 declare i64 @llvm.lround.i64.f128(double %Val) 14980 declare i64 @llvm.lround.i64.ppcf128(double %Val) 14981 14982Overview: 14983""""""""" 14984 14985The '``llvm.llround.*``' intrinsics return the operand rounded to the nearest 14986integer with ties away from zero. 14987 14988Arguments: 14989"""""""""" 14990 14991The argument is a floating-point number and the return value is an integer 14992type. 14993 14994Semantics: 14995"""""""""" 14996 14997This function returns the same values as the libm ``llround`` 14998functions would, but without setting errno. 14999 15000'``llvm.lrint.*``' Intrinsic 15001^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15002 15003Syntax: 15004""""""" 15005 15006This is an overloaded intrinsic. You can use ``llvm.lrint`` on any 15007floating-point type. Not all targets support all types however. 15008 15009:: 15010 15011 declare i32 @llvm.lrint.i32.f32(float %Val) 15012 declare i32 @llvm.lrint.i32.f64(double %Val) 15013 declare i32 @llvm.lrint.i32.f80(float %Val) 15014 declare i32 @llvm.lrint.i32.f128(double %Val) 15015 declare i32 @llvm.lrint.i32.ppcf128(double %Val) 15016 15017 declare i64 @llvm.lrint.i64.f32(float %Val) 15018 declare i64 @llvm.lrint.i64.f64(double %Val) 15019 declare i64 @llvm.lrint.i64.f80(float %Val) 15020 declare i64 @llvm.lrint.i64.f128(double %Val) 15021 declare i64 @llvm.lrint.i64.ppcf128(double %Val) 15022 15023Overview: 15024""""""""" 15025 15026The '``llvm.lrint.*``' intrinsics return the operand rounded to the nearest 15027integer. 15028 15029 15030Arguments: 15031"""""""""" 15032 15033The argument is a floating-point number and the return value is an integer 15034type. 15035 15036Semantics: 15037"""""""""" 15038 15039This function returns the same values as the libm ``lrint`` 15040functions would, but without setting errno. 15041 15042'``llvm.llrint.*``' Intrinsic 15043^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15044 15045Syntax: 15046""""""" 15047 15048This is an overloaded intrinsic. You can use ``llvm.llrint`` on any 15049floating-point type. Not all targets support all types however. 15050 15051:: 15052 15053 declare i64 @llvm.llrint.i64.f32(float %Val) 15054 declare i64 @llvm.llrint.i64.f64(double %Val) 15055 declare i64 @llvm.llrint.i64.f80(float %Val) 15056 declare i64 @llvm.llrint.i64.f128(double %Val) 15057 declare i64 @llvm.llrint.i64.ppcf128(double %Val) 15058 15059Overview: 15060""""""""" 15061 15062The '``llvm.llrint.*``' intrinsics return the operand rounded to the nearest 15063integer. 15064 15065Arguments: 15066"""""""""" 15067 15068The argument is a floating-point number and the return value is an integer 15069type. 15070 15071Semantics: 15072"""""""""" 15073 15074This function returns the same values as the libm ``llrint`` 15075functions would, but without setting errno. 15076 15077Bit Manipulation Intrinsics 15078--------------------------- 15079 15080LLVM provides intrinsics for a few important bit manipulation 15081operations. These allow efficient code generation for some algorithms. 15082 15083'``llvm.bitreverse.*``' Intrinsics 15084^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15085 15086Syntax: 15087""""""" 15088 15089This is an overloaded intrinsic function. You can use bitreverse on any 15090integer type. 15091 15092:: 15093 15094 declare i16 @llvm.bitreverse.i16(i16 <id>) 15095 declare i32 @llvm.bitreverse.i32(i32 <id>) 15096 declare i64 @llvm.bitreverse.i64(i64 <id>) 15097 declare <4 x i32> @llvm.bitreverse.v4i32(<4 x i32> <id>) 15098 15099Overview: 15100""""""""" 15101 15102The '``llvm.bitreverse``' family of intrinsics is used to reverse the 15103bitpattern of an integer value or vector of integer values; for example 15104``0b10110110`` becomes ``0b01101101``. 15105 15106Semantics: 15107"""""""""" 15108 15109The ``llvm.bitreverse.iN`` intrinsic returns an iN value that has bit 15110``M`` in the input moved to bit ``N-M-1`` in the output. The vector 15111intrinsics, such as ``llvm.bitreverse.v4i32``, operate on a per-element 15112basis and the element order is not affected. 15113 15114'``llvm.bswap.*``' Intrinsics 15115^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15116 15117Syntax: 15118""""""" 15119 15120This is an overloaded intrinsic function. You can use bswap on any 15121integer type that is an even number of bytes (i.e. BitWidth % 16 == 0). 15122 15123:: 15124 15125 declare i16 @llvm.bswap.i16(i16 <id>) 15126 declare i32 @llvm.bswap.i32(i32 <id>) 15127 declare i64 @llvm.bswap.i64(i64 <id>) 15128 declare <4 x i32> @llvm.bswap.v4i32(<4 x i32> <id>) 15129 15130Overview: 15131""""""""" 15132 15133The '``llvm.bswap``' family of intrinsics is used to byte swap an integer 15134value or vector of integer values with an even number of bytes (positive 15135multiple of 16 bits). 15136 15137Semantics: 15138"""""""""" 15139 15140The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high 15141and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32`` 15142intrinsic returns an i32 value that has the four bytes of the input i32 15143swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the 15144returned i32 will have its bytes in 3, 2, 1, 0 order. The 15145``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this 15146concept to additional even-byte lengths (6 bytes, 8 bytes and more, 15147respectively). The vector intrinsics, such as ``llvm.bswap.v4i32``, 15148operate on a per-element basis and the element order is not affected. 15149 15150'``llvm.ctpop.*``' Intrinsic 15151^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15152 15153Syntax: 15154""""""" 15155 15156This is an overloaded intrinsic. You can use llvm.ctpop on any integer 15157bit width, or on any vector with integer elements. Not all targets 15158support all bit widths or vector types, however. 15159 15160:: 15161 15162 declare i8 @llvm.ctpop.i8(i8 <src>) 15163 declare i16 @llvm.ctpop.i16(i16 <src>) 15164 declare i32 @llvm.ctpop.i32(i32 <src>) 15165 declare i64 @llvm.ctpop.i64(i64 <src>) 15166 declare i256 @llvm.ctpop.i256(i256 <src>) 15167 declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>) 15168 15169Overview: 15170""""""""" 15171 15172The '``llvm.ctpop``' family of intrinsics counts the number of bits set 15173in a value. 15174 15175Arguments: 15176"""""""""" 15177 15178The only argument is the value to be counted. The argument may be of any 15179integer type, or a vector with integer elements. The return type must 15180match the argument type. 15181 15182Semantics: 15183"""""""""" 15184 15185The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within 15186each element of a vector. 15187 15188'``llvm.ctlz.*``' Intrinsic 15189^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15190 15191Syntax: 15192""""""" 15193 15194This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any 15195integer bit width, or any vector whose elements are integers. Not all 15196targets support all bit widths or vector types, however. 15197 15198:: 15199 15200 declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_poison>) 15201 declare <2 x i37> @llvm.ctlz.v2i37(<2 x i37> <src>, i1 <is_zero_poison>) 15202 15203Overview: 15204""""""""" 15205 15206The '``llvm.ctlz``' family of intrinsic functions counts the number of 15207leading zeros in a variable. 15208 15209Arguments: 15210"""""""""" 15211 15212The first argument is the value to be counted. This argument may be of 15213any integer type, or a vector with integer element type. The return 15214type must match the first argument type. 15215 15216The second argument is a constant flag that indicates whether the intrinsic 15217returns a valid result if the first argument is zero. If the first 15218argument is zero and the second argument is true, the result is poison. 15219Historically some architectures did not provide a defined result for zero 15220values as efficiently, and many algorithms are now predicated on avoiding 15221zero-value inputs. 15222 15223Semantics: 15224"""""""""" 15225 15226The '``llvm.ctlz``' intrinsic counts the leading (most significant) 15227zeros in a variable, or within each element of the vector. If 15228``src == 0`` then the result is the size in bits of the type of ``src`` 15229if ``is_zero_poison == 0`` and ``poison`` otherwise. For example, 15230``llvm.ctlz(i32 2) = 30``. 15231 15232'``llvm.cttz.*``' Intrinsic 15233^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15234 15235Syntax: 15236""""""" 15237 15238This is an overloaded intrinsic. You can use ``llvm.cttz`` on any 15239integer bit width, or any vector of integer elements. Not all targets 15240support all bit widths or vector types, however. 15241 15242:: 15243 15244 declare i42 @llvm.cttz.i42 (i42 <src>, i1 <is_zero_poison>) 15245 declare <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_poison>) 15246 15247Overview: 15248""""""""" 15249 15250The '``llvm.cttz``' family of intrinsic functions counts the number of 15251trailing zeros. 15252 15253Arguments: 15254"""""""""" 15255 15256The first argument is the value to be counted. This argument may be of 15257any integer type, or a vector with integer element type. The return 15258type must match the first argument type. 15259 15260The second argument is a constant flag that indicates whether the intrinsic 15261returns a valid result if the first argument is zero. If the first 15262argument is zero and the second argument is true, the result is poison. 15263Historically some architectures did not provide a defined result for zero 15264values as efficiently, and many algorithms are now predicated on avoiding 15265zero-value inputs. 15266 15267Semantics: 15268"""""""""" 15269 15270The '``llvm.cttz``' intrinsic counts the trailing (least significant) 15271zeros in a variable, or within each element of a vector. If ``src == 0`` 15272then the result is the size in bits of the type of ``src`` if 15273``is_zero_poison == 0`` and ``poison`` otherwise. For example, 15274``llvm.cttz(2) = 1``. 15275 15276.. _int_overflow: 15277 15278'``llvm.fshl.*``' Intrinsic 15279^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15280 15281Syntax: 15282""""""" 15283 15284This is an overloaded intrinsic. You can use ``llvm.fshl`` on any 15285integer bit width or any vector of integer elements. Not all targets 15286support all bit widths or vector types, however. 15287 15288:: 15289 15290 declare i8 @llvm.fshl.i8 (i8 %a, i8 %b, i8 %c) 15291 declare i67 @llvm.fshl.i67(i67 %a, i67 %b, i67 %c) 15292 declare <2 x i32> @llvm.fshl.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c) 15293 15294Overview: 15295""""""""" 15296 15297The '``llvm.fshl``' family of intrinsic functions performs a funnel shift left: 15298the first two values are concatenated as { %a : %b } (%a is the most significant 15299bits of the wide value), the combined value is shifted left, and the most 15300significant bits are extracted to produce a result that is the same size as the 15301original arguments. If the first 2 arguments are identical, this is equivalent 15302to a rotate left operation. For vector types, the operation occurs for each 15303element of the vector. The shift argument is treated as an unsigned amount 15304modulo the element size of the arguments. 15305 15306Arguments: 15307"""""""""" 15308 15309The first two arguments are the values to be concatenated. The third 15310argument is the shift amount. The arguments may be any integer type or a 15311vector with integer element type. All arguments and the return value must 15312have the same type. 15313 15314Example: 15315"""""""" 15316 15317.. code-block:: text 15318 15319 %r = call i8 @llvm.fshl.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: msb_extract((concat(x, y) << (z % 8)), 8) 15320 %r = call i8 @llvm.fshl.i8(i8 255, i8 0, i8 15) ; %r = i8: 128 (0b10000000) 15321 %r = call i8 @llvm.fshl.i8(i8 15, i8 15, i8 11) ; %r = i8: 120 (0b01111000) 15322 %r = call i8 @llvm.fshl.i8(i8 0, i8 255, i8 8) ; %r = i8: 0 (0b00000000) 15323 15324'``llvm.fshr.*``' Intrinsic 15325^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15326 15327Syntax: 15328""""""" 15329 15330This is an overloaded intrinsic. You can use ``llvm.fshr`` on any 15331integer bit width or any vector of integer elements. Not all targets 15332support all bit widths or vector types, however. 15333 15334:: 15335 15336 declare i8 @llvm.fshr.i8 (i8 %a, i8 %b, i8 %c) 15337 declare i67 @llvm.fshr.i67(i67 %a, i67 %b, i67 %c) 15338 declare <2 x i32> @llvm.fshr.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c) 15339 15340Overview: 15341""""""""" 15342 15343The '``llvm.fshr``' family of intrinsic functions performs a funnel shift right: 15344the first two values are concatenated as { %a : %b } (%a is the most significant 15345bits of the wide value), the combined value is shifted right, and the least 15346significant bits are extracted to produce a result that is the same size as the 15347original arguments. If the first 2 arguments are identical, this is equivalent 15348to a rotate right operation. For vector types, the operation occurs for each 15349element of the vector. The shift argument is treated as an unsigned amount 15350modulo the element size of the arguments. 15351 15352Arguments: 15353"""""""""" 15354 15355The first two arguments are the values to be concatenated. The third 15356argument is the shift amount. The arguments may be any integer type or a 15357vector with integer element type. All arguments and the return value must 15358have the same type. 15359 15360Example: 15361"""""""" 15362 15363.. code-block:: text 15364 15365 %r = call i8 @llvm.fshr.i8(i8 %x, i8 %y, i8 %z) ; %r = i8: lsb_extract((concat(x, y) >> (z % 8)), 8) 15366 %r = call i8 @llvm.fshr.i8(i8 255, i8 0, i8 15) ; %r = i8: 254 (0b11111110) 15367 %r = call i8 @llvm.fshr.i8(i8 15, i8 15, i8 11) ; %r = i8: 225 (0b11100001) 15368 %r = call i8 @llvm.fshr.i8(i8 0, i8 255, i8 8) ; %r = i8: 255 (0b11111111) 15369 15370Arithmetic with Overflow Intrinsics 15371----------------------------------- 15372 15373LLVM provides intrinsics for fast arithmetic overflow checking. 15374 15375Each of these intrinsics returns a two-element struct. The first 15376element of this struct contains the result of the corresponding 15377arithmetic operation modulo 2\ :sup:`n`\ , where n is the bit width of 15378the result. Therefore, for example, the first element of the struct 15379returned by ``llvm.sadd.with.overflow.i32`` is always the same as the 15380result of a 32-bit ``add`` instruction with the same operands, where 15381the ``add`` is *not* modified by an ``nsw`` or ``nuw`` flag. 15382 15383The second element of the result is an ``i1`` that is 1 if the 15384arithmetic operation overflowed and 0 otherwise. An operation 15385overflows if, for any values of its operands ``A`` and ``B`` and for 15386any ``N`` larger than the operands' width, ``ext(A op B) to iN`` is 15387not equal to ``(ext(A) to iN) op (ext(B) to iN)`` where ``ext`` is 15388``sext`` for signed overflow and ``zext`` for unsigned overflow, and 15389``op`` is the underlying arithmetic operation. 15390 15391The behavior of these intrinsics is well-defined for all argument 15392values. 15393 15394'``llvm.sadd.with.overflow.*``' Intrinsics 15395^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15396 15397Syntax: 15398""""""" 15399 15400This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow`` 15401on any integer bit width or vectors of integers. 15402 15403:: 15404 15405 declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) 15406 declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 15407 declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b) 15408 declare {<4 x i32>, <4 x i1>} @llvm.sadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 15409 15410Overview: 15411""""""""" 15412 15413The '``llvm.sadd.with.overflow``' family of intrinsic functions perform 15414a signed addition of the two arguments, and indicate whether an overflow 15415occurred during the signed summation. 15416 15417Arguments: 15418"""""""""" 15419 15420The arguments (%a and %b) and the first element of the result structure 15421may be of integer types of any bit width, but they must have the same 15422bit width. The second element of the result structure must be of type 15423``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 15424addition. 15425 15426Semantics: 15427"""""""""" 15428 15429The '``llvm.sadd.with.overflow``' family of intrinsic functions perform 15430a signed addition of the two variables. They return a structure --- the 15431first element of which is the signed summation, and the second element 15432of which is a bit specifying if the signed summation resulted in an 15433overflow. 15434 15435Examples: 15436""""""""" 15437 15438.. code-block:: llvm 15439 15440 %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) 15441 %sum = extractvalue {i32, i1} %res, 0 15442 %obit = extractvalue {i32, i1} %res, 1 15443 br i1 %obit, label %overflow, label %normal 15444 15445'``llvm.uadd.with.overflow.*``' Intrinsics 15446^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15447 15448Syntax: 15449""""""" 15450 15451This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow`` 15452on any integer bit width or vectors of integers. 15453 15454:: 15455 15456 declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b) 15457 declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 15458 declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b) 15459 declare {<4 x i32>, <4 x i1>} @llvm.uadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 15460 15461Overview: 15462""""""""" 15463 15464The '``llvm.uadd.with.overflow``' family of intrinsic functions perform 15465an unsigned addition of the two arguments, and indicate whether a carry 15466occurred during the unsigned summation. 15467 15468Arguments: 15469"""""""""" 15470 15471The arguments (%a and %b) and the first element of the result structure 15472may be of integer types of any bit width, but they must have the same 15473bit width. The second element of the result structure must be of type 15474``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 15475addition. 15476 15477Semantics: 15478"""""""""" 15479 15480The '``llvm.uadd.with.overflow``' family of intrinsic functions perform 15481an unsigned addition of the two arguments. They return a structure --- the 15482first element of which is the sum, and the second element of which is a 15483bit specifying if the unsigned summation resulted in a carry. 15484 15485Examples: 15486""""""""" 15487 15488.. code-block:: llvm 15489 15490 %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) 15491 %sum = extractvalue {i32, i1} %res, 0 15492 %obit = extractvalue {i32, i1} %res, 1 15493 br i1 %obit, label %carry, label %normal 15494 15495'``llvm.ssub.with.overflow.*``' Intrinsics 15496^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15497 15498Syntax: 15499""""""" 15500 15501This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow`` 15502on any integer bit width or vectors of integers. 15503 15504:: 15505 15506 declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b) 15507 declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 15508 declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b) 15509 declare {<4 x i32>, <4 x i1>} @llvm.ssub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 15510 15511Overview: 15512""""""""" 15513 15514The '``llvm.ssub.with.overflow``' family of intrinsic functions perform 15515a signed subtraction of the two arguments, and indicate whether an 15516overflow occurred during the signed subtraction. 15517 15518Arguments: 15519"""""""""" 15520 15521The arguments (%a and %b) and the first element of the result structure 15522may be of integer types of any bit width, but they must have the same 15523bit width. The second element of the result structure must be of type 15524``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 15525subtraction. 15526 15527Semantics: 15528"""""""""" 15529 15530The '``llvm.ssub.with.overflow``' family of intrinsic functions perform 15531a signed subtraction of the two arguments. They return a structure --- the 15532first element of which is the subtraction, and the second element of 15533which is a bit specifying if the signed subtraction resulted in an 15534overflow. 15535 15536Examples: 15537""""""""" 15538 15539.. code-block:: llvm 15540 15541 %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) 15542 %sum = extractvalue {i32, i1} %res, 0 15543 %obit = extractvalue {i32, i1} %res, 1 15544 br i1 %obit, label %overflow, label %normal 15545 15546'``llvm.usub.with.overflow.*``' Intrinsics 15547^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15548 15549Syntax: 15550""""""" 15551 15552This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow`` 15553on any integer bit width or vectors of integers. 15554 15555:: 15556 15557 declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b) 15558 declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 15559 declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b) 15560 declare {<4 x i32>, <4 x i1>} @llvm.usub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 15561 15562Overview: 15563""""""""" 15564 15565The '``llvm.usub.with.overflow``' family of intrinsic functions perform 15566an unsigned subtraction of the two arguments, and indicate whether an 15567overflow occurred during the unsigned subtraction. 15568 15569Arguments: 15570"""""""""" 15571 15572The arguments (%a and %b) and the first element of the result structure 15573may be of integer types of any bit width, but they must have the same 15574bit width. The second element of the result structure must be of type 15575``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 15576subtraction. 15577 15578Semantics: 15579"""""""""" 15580 15581The '``llvm.usub.with.overflow``' family of intrinsic functions perform 15582an unsigned subtraction of the two arguments. They return a structure --- 15583the first element of which is the subtraction, and the second element of 15584which is a bit specifying if the unsigned subtraction resulted in an 15585overflow. 15586 15587Examples: 15588""""""""" 15589 15590.. code-block:: llvm 15591 15592 %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) 15593 %sum = extractvalue {i32, i1} %res, 0 15594 %obit = extractvalue {i32, i1} %res, 1 15595 br i1 %obit, label %overflow, label %normal 15596 15597'``llvm.smul.with.overflow.*``' Intrinsics 15598^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15599 15600Syntax: 15601""""""" 15602 15603This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow`` 15604on any integer bit width or vectors of integers. 15605 15606:: 15607 15608 declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b) 15609 declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 15610 declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b) 15611 declare {<4 x i32>, <4 x i1>} @llvm.smul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 15612 15613Overview: 15614""""""""" 15615 15616The '``llvm.smul.with.overflow``' family of intrinsic functions perform 15617a signed multiplication of the two arguments, and indicate whether an 15618overflow occurred during the signed multiplication. 15619 15620Arguments: 15621"""""""""" 15622 15623The arguments (%a and %b) and the first element of the result structure 15624may be of integer types of any bit width, but they must have the same 15625bit width. The second element of the result structure must be of type 15626``i1``. ``%a`` and ``%b`` are the two values that will undergo signed 15627multiplication. 15628 15629Semantics: 15630"""""""""" 15631 15632The '``llvm.smul.with.overflow``' family of intrinsic functions perform 15633a signed multiplication of the two arguments. They return a structure --- 15634the first element of which is the multiplication, and the second element 15635of which is a bit specifying if the signed multiplication resulted in an 15636overflow. 15637 15638Examples: 15639""""""""" 15640 15641.. code-block:: llvm 15642 15643 %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) 15644 %sum = extractvalue {i32, i1} %res, 0 15645 %obit = extractvalue {i32, i1} %res, 1 15646 br i1 %obit, label %overflow, label %normal 15647 15648'``llvm.umul.with.overflow.*``' Intrinsics 15649^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15650 15651Syntax: 15652""""""" 15653 15654This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow`` 15655on any integer bit width or vectors of integers. 15656 15657:: 15658 15659 declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b) 15660 declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 15661 declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b) 15662 declare {<4 x i32>, <4 x i1>} @llvm.umul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b) 15663 15664Overview: 15665""""""""" 15666 15667The '``llvm.umul.with.overflow``' family of intrinsic functions perform 15668a unsigned multiplication of the two arguments, and indicate whether an 15669overflow occurred during the unsigned multiplication. 15670 15671Arguments: 15672"""""""""" 15673 15674The arguments (%a and %b) and the first element of the result structure 15675may be of integer types of any bit width, but they must have the same 15676bit width. The second element of the result structure must be of type 15677``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned 15678multiplication. 15679 15680Semantics: 15681"""""""""" 15682 15683The '``llvm.umul.with.overflow``' family of intrinsic functions perform 15684an unsigned multiplication of the two arguments. They return a structure --- 15685the first element of which is the multiplication, and the second 15686element of which is a bit specifying if the unsigned multiplication 15687resulted in an overflow. 15688 15689Examples: 15690""""""""" 15691 15692.. code-block:: llvm 15693 15694 %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) 15695 %sum = extractvalue {i32, i1} %res, 0 15696 %obit = extractvalue {i32, i1} %res, 1 15697 br i1 %obit, label %overflow, label %normal 15698 15699Saturation Arithmetic Intrinsics 15700--------------------------------- 15701 15702Saturation arithmetic is a version of arithmetic in which operations are 15703limited to a fixed range between a minimum and maximum value. If the result of 15704an operation is greater than the maximum value, the result is set (or 15705"clamped") to this maximum. If it is below the minimum, it is clamped to this 15706minimum. 15707 15708 15709'``llvm.sadd.sat.*``' Intrinsics 15710^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15711 15712Syntax 15713""""""" 15714 15715This is an overloaded intrinsic. You can use ``llvm.sadd.sat`` 15716on any integer bit width or vectors of integers. 15717 15718:: 15719 15720 declare i16 @llvm.sadd.sat.i16(i16 %a, i16 %b) 15721 declare i32 @llvm.sadd.sat.i32(i32 %a, i32 %b) 15722 declare i64 @llvm.sadd.sat.i64(i64 %a, i64 %b) 15723 declare <4 x i32> @llvm.sadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15724 15725Overview 15726""""""""" 15727 15728The '``llvm.sadd.sat``' family of intrinsic functions perform signed 15729saturating addition on the 2 arguments. 15730 15731Arguments 15732"""""""""" 15733 15734The arguments (%a and %b) and the result may be of integer types of any bit 15735width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15736values that will undergo signed addition. 15737 15738Semantics: 15739"""""""""" 15740 15741The maximum value this operation can clamp to is the largest signed value 15742representable by the bit width of the arguments. The minimum value is the 15743smallest signed value representable by this bit width. 15744 15745 15746Examples 15747""""""""" 15748 15749.. code-block:: llvm 15750 15751 %res = call i4 @llvm.sadd.sat.i4(i4 1, i4 2) ; %res = 3 15752 %res = call i4 @llvm.sadd.sat.i4(i4 5, i4 6) ; %res = 7 15753 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 2) ; %res = -2 15754 %res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 -5) ; %res = -8 15755 15756 15757'``llvm.uadd.sat.*``' Intrinsics 15758^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15759 15760Syntax 15761""""""" 15762 15763This is an overloaded intrinsic. You can use ``llvm.uadd.sat`` 15764on any integer bit width or vectors of integers. 15765 15766:: 15767 15768 declare i16 @llvm.uadd.sat.i16(i16 %a, i16 %b) 15769 declare i32 @llvm.uadd.sat.i32(i32 %a, i32 %b) 15770 declare i64 @llvm.uadd.sat.i64(i64 %a, i64 %b) 15771 declare <4 x i32> @llvm.uadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15772 15773Overview 15774""""""""" 15775 15776The '``llvm.uadd.sat``' family of intrinsic functions perform unsigned 15777saturating addition on the 2 arguments. 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. ``%a`` and ``%b`` are the two 15784values that will undergo unsigned addition. 15785 15786Semantics: 15787"""""""""" 15788 15789The maximum value this operation can clamp to is the largest unsigned value 15790representable by the bit width of the arguments. Because this is an unsigned 15791operation, the result will never saturate towards zero. 15792 15793 15794Examples 15795""""""""" 15796 15797.. code-block:: llvm 15798 15799 %res = call i4 @llvm.uadd.sat.i4(i4 1, i4 2) ; %res = 3 15800 %res = call i4 @llvm.uadd.sat.i4(i4 5, i4 6) ; %res = 11 15801 %res = call i4 @llvm.uadd.sat.i4(i4 8, i4 8) ; %res = 15 15802 15803 15804'``llvm.ssub.sat.*``' Intrinsics 15805^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15806 15807Syntax 15808""""""" 15809 15810This is an overloaded intrinsic. You can use ``llvm.ssub.sat`` 15811on any integer bit width or vectors of integers. 15812 15813:: 15814 15815 declare i16 @llvm.ssub.sat.i16(i16 %a, i16 %b) 15816 declare i32 @llvm.ssub.sat.i32(i32 %a, i32 %b) 15817 declare i64 @llvm.ssub.sat.i64(i64 %a, i64 %b) 15818 declare <4 x i32> @llvm.ssub.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15819 15820Overview 15821""""""""" 15822 15823The '``llvm.ssub.sat``' family of intrinsic functions perform signed 15824saturating subtraction on the 2 arguments. 15825 15826Arguments 15827"""""""""" 15828 15829The arguments (%a and %b) and the result may be of integer types of any bit 15830width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15831values that will undergo signed subtraction. 15832 15833Semantics: 15834"""""""""" 15835 15836The maximum value this operation can clamp to is the largest signed value 15837representable by the bit width of the arguments. The minimum value is the 15838smallest signed value representable by this bit width. 15839 15840 15841Examples 15842""""""""" 15843 15844.. code-block:: llvm 15845 15846 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 1) ; %res = 1 15847 %res = call i4 @llvm.ssub.sat.i4(i4 2, i4 6) ; %res = -4 15848 %res = call i4 @llvm.ssub.sat.i4(i4 -4, i4 5) ; %res = -8 15849 %res = call i4 @llvm.ssub.sat.i4(i4 4, i4 -5) ; %res = 7 15850 15851 15852'``llvm.usub.sat.*``' Intrinsics 15853^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15854 15855Syntax 15856""""""" 15857 15858This is an overloaded intrinsic. You can use ``llvm.usub.sat`` 15859on any integer bit width or vectors of integers. 15860 15861:: 15862 15863 declare i16 @llvm.usub.sat.i16(i16 %a, i16 %b) 15864 declare i32 @llvm.usub.sat.i32(i32 %a, i32 %b) 15865 declare i64 @llvm.usub.sat.i64(i64 %a, i64 %b) 15866 declare <4 x i32> @llvm.usub.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15867 15868Overview 15869""""""""" 15870 15871The '``llvm.usub.sat``' family of intrinsic functions perform unsigned 15872saturating subtraction on the 2 arguments. 15873 15874Arguments 15875"""""""""" 15876 15877The arguments (%a and %b) and the result may be of integer types of any bit 15878width, but they must have the same bit width. ``%a`` and ``%b`` are the two 15879values that will undergo unsigned subtraction. 15880 15881Semantics: 15882"""""""""" 15883 15884The minimum value this operation can clamp to is 0, which is the smallest 15885unsigned value representable by the bit width of the unsigned arguments. 15886Because this is an unsigned operation, the result will never saturate towards 15887the largest possible value representable by this bit width. 15888 15889 15890Examples 15891""""""""" 15892 15893.. code-block:: llvm 15894 15895 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 1) ; %res = 1 15896 %res = call i4 @llvm.usub.sat.i4(i4 2, i4 6) ; %res = 0 15897 15898 15899'``llvm.sshl.sat.*``' Intrinsics 15900^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15901 15902Syntax 15903""""""" 15904 15905This is an overloaded intrinsic. You can use ``llvm.sshl.sat`` 15906on integers or vectors of integers of any bit width. 15907 15908:: 15909 15910 declare i16 @llvm.sshl.sat.i16(i16 %a, i16 %b) 15911 declare i32 @llvm.sshl.sat.i32(i32 %a, i32 %b) 15912 declare i64 @llvm.sshl.sat.i64(i64 %a, i64 %b) 15913 declare <4 x i32> @llvm.sshl.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15914 15915Overview 15916""""""""" 15917 15918The '``llvm.sshl.sat``' family of intrinsic functions perform signed 15919saturating left shift on the first argument. 15920 15921Arguments 15922"""""""""" 15923 15924The arguments (``%a`` and ``%b``) and the result may be of integer types of any 15925bit width, but they must have the same bit width. ``%a`` is the value to be 15926shifted, and ``%b`` is the amount to shift by. If ``b`` is (statically or 15927dynamically) equal to or larger than the integer bit width of the arguments, 15928the result is a :ref:`poison value <poisonvalues>`. If the arguments are 15929vectors, each vector element of ``a`` is shifted by the corresponding shift 15930amount in ``b``. 15931 15932 15933Semantics: 15934"""""""""" 15935 15936The maximum value this operation can clamp to is the largest signed value 15937representable by the bit width of the arguments. The minimum value is the 15938smallest signed value representable by this bit width. 15939 15940 15941Examples 15942""""""""" 15943 15944.. code-block:: llvm 15945 15946 %res = call i4 @llvm.sshl.sat.i4(i4 2, i4 1) ; %res = 4 15947 %res = call i4 @llvm.sshl.sat.i4(i4 2, i4 2) ; %res = 7 15948 %res = call i4 @llvm.sshl.sat.i4(i4 -5, i4 1) ; %res = -8 15949 %res = call i4 @llvm.sshl.sat.i4(i4 -1, i4 1) ; %res = -2 15950 15951 15952'``llvm.ushl.sat.*``' Intrinsics 15953^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 15954 15955Syntax 15956""""""" 15957 15958This is an overloaded intrinsic. You can use ``llvm.ushl.sat`` 15959on integers or vectors of integers of any bit width. 15960 15961:: 15962 15963 declare i16 @llvm.ushl.sat.i16(i16 %a, i16 %b) 15964 declare i32 @llvm.ushl.sat.i32(i32 %a, i32 %b) 15965 declare i64 @llvm.ushl.sat.i64(i64 %a, i64 %b) 15966 declare <4 x i32> @llvm.ushl.sat.v4i32(<4 x i32> %a, <4 x i32> %b) 15967 15968Overview 15969""""""""" 15970 15971The '``llvm.ushl.sat``' family of intrinsic functions perform unsigned 15972saturating left shift on the first argument. 15973 15974Arguments 15975"""""""""" 15976 15977The arguments (``%a`` and ``%b``) and the result may be of integer types of any 15978bit width, but they must have the same bit width. ``%a`` is the value to be 15979shifted, and ``%b`` is the amount to shift by. If ``b`` is (statically or 15980dynamically) equal to or larger than the integer bit width of the arguments, 15981the result is a :ref:`poison value <poisonvalues>`. If the arguments are 15982vectors, each vector element of ``a`` is shifted by the corresponding shift 15983amount in ``b``. 15984 15985Semantics: 15986"""""""""" 15987 15988The maximum value this operation can clamp to is the largest unsigned value 15989representable by the bit width of the arguments. 15990 15991 15992Examples 15993""""""""" 15994 15995.. code-block:: llvm 15996 15997 %res = call i4 @llvm.ushl.sat.i4(i4 2, i4 1) ; %res = 4 15998 %res = call i4 @llvm.ushl.sat.i4(i4 3, i4 3) ; %res = 15 15999 16000 16001Fixed Point Arithmetic Intrinsics 16002--------------------------------- 16003 16004A fixed point number represents a real data type for a number that has a fixed 16005number of digits after a radix point (equivalent to the decimal point '.'). 16006The number of digits after the radix point is referred as the `scale`. These 16007are useful for representing fractional values to a specific precision. The 16008following intrinsics perform fixed point arithmetic operations on 2 operands 16009of the same scale, specified as the third argument. 16010 16011The ``llvm.*mul.fix`` family of intrinsic functions represents a multiplication 16012of fixed point numbers through scaled integers. Therefore, fixed point 16013multiplication can be represented as 16014 16015.. code-block:: llvm 16016 16017 %result = call i4 @llvm.smul.fix.i4(i4 %a, i4 %b, i32 %scale) 16018 16019 ; Expands to 16020 %a2 = sext i4 %a to i8 16021 %b2 = sext i4 %b to i8 16022 %mul = mul nsw nuw i8 %a2, %b2 16023 %scale2 = trunc i32 %scale to i8 16024 %r = ashr i8 %mul, i8 %scale2 ; this is for a target rounding down towards negative infinity 16025 %result = trunc i8 %r to i4 16026 16027The ``llvm.*div.fix`` family of intrinsic functions represents a division of 16028fixed point numbers through scaled integers. Fixed point division can be 16029represented as: 16030 16031.. code-block:: llvm 16032 16033 %result call i4 @llvm.sdiv.fix.i4(i4 %a, i4 %b, i32 %scale) 16034 16035 ; Expands to 16036 %a2 = sext i4 %a to i8 16037 %b2 = sext i4 %b to i8 16038 %scale2 = trunc i32 %scale to i8 16039 %a3 = shl i8 %a2, %scale2 16040 %r = sdiv i8 %a3, %b2 ; this is for a target rounding towards zero 16041 %result = trunc i8 %r to i4 16042 16043For each of these functions, if the result cannot be represented exactly with 16044the provided scale, the result is rounded. Rounding is unspecified since 16045preferred rounding may vary for different targets. Rounding is specified 16046through a target hook. Different pipelines should legalize or optimize this 16047using the rounding specified by this hook if it is provided. Operations like 16048constant folding, instruction combining, KnownBits, and ValueTracking should 16049also use this hook, if provided, and not assume the direction of rounding. A 16050rounded result must always be within one unit of precision from the true 16051result. That is, the error between the returned result and the true result must 16052be less than 1/2^(scale). 16053 16054 16055'``llvm.smul.fix.*``' Intrinsics 16056^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16057 16058Syntax 16059""""""" 16060 16061This is an overloaded intrinsic. You can use ``llvm.smul.fix`` 16062on any integer bit width or vectors of integers. 16063 16064:: 16065 16066 declare i16 @llvm.smul.fix.i16(i16 %a, i16 %b, i32 %scale) 16067 declare i32 @llvm.smul.fix.i32(i32 %a, i32 %b, i32 %scale) 16068 declare i64 @llvm.smul.fix.i64(i64 %a, i64 %b, i32 %scale) 16069 declare <4 x i32> @llvm.smul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16070 16071Overview 16072""""""""" 16073 16074The '``llvm.smul.fix``' family of intrinsic functions perform signed 16075fixed point multiplication on 2 arguments of the same scale. 16076 16077Arguments 16078"""""""""" 16079 16080The arguments (%a and %b) and the result may be of integer types of any bit 16081width, but they must have the same bit width. The arguments may also work with 16082int vectors of the same length and int size. ``%a`` and ``%b`` are the two 16083values that will undergo signed fixed point multiplication. The argument 16084``%scale`` represents the scale of both operands, and must be a constant 16085integer. 16086 16087Semantics: 16088"""""""""" 16089 16090This operation performs fixed point multiplication on the 2 arguments of a 16091specified scale. The result will also be returned in the same scale specified 16092in the third argument. 16093 16094If the result value cannot be precisely represented in the given scale, the 16095value is rounded up or down to the closest representable value. The rounding 16096direction is unspecified. 16097 16098It is undefined behavior if the result value does not fit within the range of 16099the fixed point type. 16100 16101 16102Examples 16103""""""""" 16104 16105.. code-block:: llvm 16106 16107 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 16108 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 16109 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 x -1 = -1.5) 16110 16111 ; The result in the following could be rounded up to -2 or down to -2.5 16112 %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -3, i32 1) ; %res = -5 (or -4) (1.5 x -1.5 = -2.25) 16113 16114 16115'``llvm.umul.fix.*``' Intrinsics 16116^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16117 16118Syntax 16119""""""" 16120 16121This is an overloaded intrinsic. You can use ``llvm.umul.fix`` 16122on any integer bit width or vectors of integers. 16123 16124:: 16125 16126 declare i16 @llvm.umul.fix.i16(i16 %a, i16 %b, i32 %scale) 16127 declare i32 @llvm.umul.fix.i32(i32 %a, i32 %b, i32 %scale) 16128 declare i64 @llvm.umul.fix.i64(i64 %a, i64 %b, i32 %scale) 16129 declare <4 x i32> @llvm.umul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16130 16131Overview 16132""""""""" 16133 16134The '``llvm.umul.fix``' family of intrinsic functions perform unsigned 16135fixed point multiplication on 2 arguments of the same scale. 16136 16137Arguments 16138"""""""""" 16139 16140The arguments (%a and %b) and the result may be of integer types of any bit 16141width, but they must have the same bit width. The arguments may also work with 16142int vectors of the same length and int size. ``%a`` and ``%b`` are the two 16143values that will undergo unsigned fixed point multiplication. The argument 16144``%scale`` represents the scale of both operands, and must be a constant 16145integer. 16146 16147Semantics: 16148"""""""""" 16149 16150This operation performs unsigned fixed point multiplication on the 2 arguments of a 16151specified scale. The result will also be returned in the same scale specified 16152in the third argument. 16153 16154If the result value cannot be precisely represented in the given scale, the 16155value is rounded up or down to the closest representable value. The rounding 16156direction is unspecified. 16157 16158It is undefined behavior if the result value does not fit within the range of 16159the fixed point type. 16160 16161 16162Examples 16163""""""""" 16164 16165.. code-block:: llvm 16166 16167 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 16168 %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 16169 16170 ; The result in the following could be rounded down to 3.5 or up to 4 16171 %res = call i4 @llvm.umul.fix.i4(i4 15, i4 1, i32 1) ; %res = 7 (or 8) (7.5 x 0.5 = 3.75) 16172 16173 16174'``llvm.smul.fix.sat.*``' Intrinsics 16175^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16176 16177Syntax 16178""""""" 16179 16180This is an overloaded intrinsic. You can use ``llvm.smul.fix.sat`` 16181on any integer bit width or vectors of integers. 16182 16183:: 16184 16185 declare i16 @llvm.smul.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 16186 declare i32 @llvm.smul.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 16187 declare i64 @llvm.smul.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 16188 declare <4 x i32> @llvm.smul.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16189 16190Overview 16191""""""""" 16192 16193The '``llvm.smul.fix.sat``' family of intrinsic functions perform signed 16194fixed point saturating multiplication on 2 arguments of the same scale. 16195 16196Arguments 16197"""""""""" 16198 16199The arguments (%a and %b) and the result may be of integer types of any bit 16200width, but they must have the same bit width. ``%a`` and ``%b`` are the two 16201values that will undergo signed fixed point multiplication. The argument 16202``%scale`` represents the scale of both operands, and must be a constant 16203integer. 16204 16205Semantics: 16206"""""""""" 16207 16208This operation performs fixed point multiplication on the 2 arguments of a 16209specified scale. The result will also be returned in the same scale specified 16210in the third argument. 16211 16212If the result value cannot be precisely represented in the given scale, the 16213value is rounded up or down to the closest representable value. The rounding 16214direction is unspecified. 16215 16216The maximum value this operation can clamp to is the largest signed value 16217representable by the bit width of the first 2 arguments. The minimum value is the 16218smallest signed value representable by this bit width. 16219 16220 16221Examples 16222""""""""" 16223 16224.. code-block:: llvm 16225 16226 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 16227 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 16228 %res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 x -1 = -1.5) 16229 16230 ; The result in the following could be rounded up to -2 or down to -2.5 16231 %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) 16232 16233 ; Saturation 16234 %res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 2, i32 0) ; %res = 7 16235 %res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 4, i32 2) ; %res = 7 16236 %res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 5, i32 2) ; %res = -8 16237 %res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 -2, i32 1) ; %res = 7 16238 16239 ; Scale can affect the saturation result 16240 %res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 0) ; %res = 7 (2 x 4 -> clamped to 7) 16241 %res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 1) ; %res = 4 (1 x 2 = 2) 16242 16243 16244'``llvm.umul.fix.sat.*``' Intrinsics 16245^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16246 16247Syntax 16248""""""" 16249 16250This is an overloaded intrinsic. You can use ``llvm.umul.fix.sat`` 16251on any integer bit width or vectors of integers. 16252 16253:: 16254 16255 declare i16 @llvm.umul.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 16256 declare i32 @llvm.umul.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 16257 declare i64 @llvm.umul.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 16258 declare <4 x i32> @llvm.umul.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16259 16260Overview 16261""""""""" 16262 16263The '``llvm.umul.fix.sat``' family of intrinsic functions perform unsigned 16264fixed point saturating multiplication on 2 arguments of the same scale. 16265 16266Arguments 16267"""""""""" 16268 16269The arguments (%a and %b) and the result may be of integer types of any bit 16270width, but they must have the same bit width. ``%a`` and ``%b`` are the two 16271values that will undergo unsigned fixed point multiplication. The argument 16272``%scale`` represents the scale of both operands, and must be a constant 16273integer. 16274 16275Semantics: 16276"""""""""" 16277 16278This operation performs fixed point multiplication on the 2 arguments of a 16279specified scale. The result will also be returned in the same scale specified 16280in the third argument. 16281 16282If the result value cannot be precisely represented in the given scale, the 16283value is rounded up or down to the closest representable value. The rounding 16284direction is unspecified. 16285 16286The maximum value this operation can clamp to is the largest unsigned value 16287representable by the bit width of the first 2 arguments. The minimum value is the 16288smallest unsigned value representable by this bit width (zero). 16289 16290 16291Examples 16292""""""""" 16293 16294.. code-block:: llvm 16295 16296 %res = call i4 @llvm.umul.fix.sat.i4(i4 3, i4 2, i32 0) ; %res = 6 (2 x 3 = 6) 16297 %res = call i4 @llvm.umul.fix.sat.i4(i4 3, i4 2, i32 1) ; %res = 3 (1.5 x 1 = 1.5) 16298 16299 ; The result in the following could be rounded down to 2 or up to 2.5 16300 %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) 16301 16302 ; Saturation 16303 %res = call i4 @llvm.umul.fix.sat.i4(i4 8, i4 2, i32 0) ; %res = 15 (8 x 2 -> clamped to 15) 16304 %res = call i4 @llvm.umul.fix.sat.i4(i4 8, i4 8, i32 2) ; %res = 15 (2 x 2 -> clamped to 3.75) 16305 16306 ; Scale can affect the saturation result 16307 %res = call i4 @llvm.umul.fix.sat.i4(i4 2, i4 4, i32 0) ; %res = 7 (2 x 4 -> clamped to 7) 16308 %res = call i4 @llvm.umul.fix.sat.i4(i4 2, i4 4, i32 1) ; %res = 4 (1 x 2 = 2) 16309 16310 16311'``llvm.sdiv.fix.*``' Intrinsics 16312^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16313 16314Syntax 16315""""""" 16316 16317This is an overloaded intrinsic. You can use ``llvm.sdiv.fix`` 16318on any integer bit width or vectors of integers. 16319 16320:: 16321 16322 declare i16 @llvm.sdiv.fix.i16(i16 %a, i16 %b, i32 %scale) 16323 declare i32 @llvm.sdiv.fix.i32(i32 %a, i32 %b, i32 %scale) 16324 declare i64 @llvm.sdiv.fix.i64(i64 %a, i64 %b, i32 %scale) 16325 declare <4 x i32> @llvm.sdiv.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16326 16327Overview 16328""""""""" 16329 16330The '``llvm.sdiv.fix``' family of intrinsic functions perform signed 16331fixed point division on 2 arguments of the same scale. 16332 16333Arguments 16334"""""""""" 16335 16336The arguments (%a and %b) and the result may be of integer types of any bit 16337width, but they must have the same bit width. The arguments may also work with 16338int vectors of the same length and int size. ``%a`` and ``%b`` are the two 16339values that will undergo signed fixed point division. The argument 16340``%scale`` represents the scale of both operands, and must be a constant 16341integer. 16342 16343Semantics: 16344"""""""""" 16345 16346This operation performs fixed point division on the 2 arguments of a 16347specified scale. The result will also be returned in the same scale specified 16348in the third argument. 16349 16350If the result value cannot be precisely represented in the given scale, the 16351value is rounded up or down to the closest representable value. The rounding 16352direction is unspecified. 16353 16354It is undefined behavior if the result value does not fit within the range of 16355the fixed point type, or if the second argument is zero. 16356 16357 16358Examples 16359""""""""" 16360 16361.. code-block:: llvm 16362 16363 %res = call i4 @llvm.sdiv.fix.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 16364 %res = call i4 @llvm.sdiv.fix.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 16365 %res = call i4 @llvm.sdiv.fix.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 / -1 = -1.5) 16366 16367 ; The result in the following could be rounded up to 1 or down to 0.5 16368 %res = call i4 @llvm.sdiv.fix.i4(i4 3, i4 4, i32 1) ; %res = 2 (or 1) (1.5 / 2 = 0.75) 16369 16370 16371'``llvm.udiv.fix.*``' Intrinsics 16372^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16373 16374Syntax 16375""""""" 16376 16377This is an overloaded intrinsic. You can use ``llvm.udiv.fix`` 16378on any integer bit width or vectors of integers. 16379 16380:: 16381 16382 declare i16 @llvm.udiv.fix.i16(i16 %a, i16 %b, i32 %scale) 16383 declare i32 @llvm.udiv.fix.i32(i32 %a, i32 %b, i32 %scale) 16384 declare i64 @llvm.udiv.fix.i64(i64 %a, i64 %b, i32 %scale) 16385 declare <4 x i32> @llvm.udiv.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16386 16387Overview 16388""""""""" 16389 16390The '``llvm.udiv.fix``' family of intrinsic functions perform unsigned 16391fixed point division on 2 arguments of the same scale. 16392 16393Arguments 16394"""""""""" 16395 16396The arguments (%a and %b) and the result may be of integer types of any bit 16397width, but they must have the same bit width. The arguments may also work with 16398int vectors of the same length and int size. ``%a`` and ``%b`` are the two 16399values that will undergo unsigned fixed point division. The argument 16400``%scale`` represents the scale of both operands, and must be a constant 16401integer. 16402 16403Semantics: 16404"""""""""" 16405 16406This operation performs fixed point division on the 2 arguments of a 16407specified scale. The result will also be returned in the same scale specified 16408in the third argument. 16409 16410If the result value cannot be precisely represented in the given scale, the 16411value is rounded up or down to the closest representable value. The rounding 16412direction is unspecified. 16413 16414It is undefined behavior if the result value does not fit within the range of 16415the fixed point type, or if the second argument is zero. 16416 16417 16418Examples 16419""""""""" 16420 16421.. code-block:: llvm 16422 16423 %res = call i4 @llvm.udiv.fix.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 16424 %res = call i4 @llvm.udiv.fix.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 16425 %res = call i4 @llvm.udiv.fix.i4(i4 1, i4 -8, i32 4) ; %res = 2 (0.0625 / 0.5 = 0.125) 16426 16427 ; The result in the following could be rounded up to 1 or down to 0.5 16428 %res = call i4 @llvm.udiv.fix.i4(i4 3, i4 4, i32 1) ; %res = 2 (or 1) (1.5 / 2 = 0.75) 16429 16430 16431'``llvm.sdiv.fix.sat.*``' Intrinsics 16432^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16433 16434Syntax 16435""""""" 16436 16437This is an overloaded intrinsic. You can use ``llvm.sdiv.fix.sat`` 16438on any integer bit width or vectors of integers. 16439 16440:: 16441 16442 declare i16 @llvm.sdiv.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 16443 declare i32 @llvm.sdiv.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 16444 declare i64 @llvm.sdiv.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 16445 declare <4 x i32> @llvm.sdiv.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16446 16447Overview 16448""""""""" 16449 16450The '``llvm.sdiv.fix.sat``' family of intrinsic functions perform signed 16451fixed point saturating division on 2 arguments of the same scale. 16452 16453Arguments 16454"""""""""" 16455 16456The arguments (%a and %b) and the result may be of integer types of any bit 16457width, but they must have the same bit width. ``%a`` and ``%b`` are the two 16458values that will undergo signed fixed point division. The argument 16459``%scale`` represents the scale of both operands, and must be a constant 16460integer. 16461 16462Semantics: 16463"""""""""" 16464 16465This operation performs fixed point division on the 2 arguments of a 16466specified scale. The result will also be returned in the same scale specified 16467in the third argument. 16468 16469If the result value cannot be precisely represented in the given scale, the 16470value is rounded up or down to the closest representable value. The rounding 16471direction is unspecified. 16472 16473The maximum value this operation can clamp to is the largest signed value 16474representable by the bit width of the first 2 arguments. The minimum value is the 16475smallest signed value representable by this bit width. 16476 16477It is undefined behavior if the second argument is zero. 16478 16479 16480Examples 16481""""""""" 16482 16483.. code-block:: llvm 16484 16485 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 16486 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 16487 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 3, i4 -2, i32 1) ; %res = -3 (1.5 / -1 = -1.5) 16488 16489 ; The result in the following could be rounded up to 1 or down to 0.5 16490 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 3, i4 4, i32 1) ; %res = 2 (or 1) (1.5 / 2 = 0.75) 16491 16492 ; Saturation 16493 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 -8, i4 -1, i32 0) ; %res = 7 (-8 / -1 = 8 => 7) 16494 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 4, i4 2, i32 2) ; %res = 7 (1 / 0.5 = 2 => 1.75) 16495 %res = call i4 @llvm.sdiv.fix.sat.i4(i4 -4, i4 1, i32 2) ; %res = -8 (-1 / 0.25 = -4 => -2) 16496 16497 16498'``llvm.udiv.fix.sat.*``' Intrinsics 16499^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16500 16501Syntax 16502""""""" 16503 16504This is an overloaded intrinsic. You can use ``llvm.udiv.fix.sat`` 16505on any integer bit width or vectors of integers. 16506 16507:: 16508 16509 declare i16 @llvm.udiv.fix.sat.i16(i16 %a, i16 %b, i32 %scale) 16510 declare i32 @llvm.udiv.fix.sat.i32(i32 %a, i32 %b, i32 %scale) 16511 declare i64 @llvm.udiv.fix.sat.i64(i64 %a, i64 %b, i32 %scale) 16512 declare <4 x i32> @llvm.udiv.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale) 16513 16514Overview 16515""""""""" 16516 16517The '``llvm.udiv.fix.sat``' family of intrinsic functions perform unsigned 16518fixed point saturating division on 2 arguments of the same scale. 16519 16520Arguments 16521"""""""""" 16522 16523The arguments (%a and %b) and the result may be of integer types of any bit 16524width, but they must have the same bit width. ``%a`` and ``%b`` are the two 16525values that will undergo unsigned fixed point division. The argument 16526``%scale`` represents the scale of both operands, and must be a constant 16527integer. 16528 16529Semantics: 16530"""""""""" 16531 16532This operation performs fixed point division on the 2 arguments of a 16533specified scale. The result will also be returned in the same scale specified 16534in the third argument. 16535 16536If the result value cannot be precisely represented in the given scale, the 16537value is rounded up or down to the closest representable value. The rounding 16538direction is unspecified. 16539 16540The maximum value this operation can clamp to is the largest unsigned value 16541representable by the bit width of the first 2 arguments. The minimum value is the 16542smallest unsigned value representable by this bit width (zero). 16543 16544It is undefined behavior if the second argument is zero. 16545 16546Examples 16547""""""""" 16548 16549.. code-block:: llvm 16550 16551 %res = call i4 @llvm.udiv.fix.sat.i4(i4 6, i4 2, i32 0) ; %res = 3 (6 / 2 = 3) 16552 %res = call i4 @llvm.udiv.fix.sat.i4(i4 6, i4 4, i32 1) ; %res = 3 (3 / 2 = 1.5) 16553 16554 ; The result in the following could be rounded down to 0.5 or up to 1 16555 %res = call i4 @llvm.udiv.fix.sat.i4(i4 3, i4 4, i32 1) ; %res = 1 (or 2) (1.5 / 2 = 0.75) 16556 16557 ; Saturation 16558 %res = call i4 @llvm.udiv.fix.sat.i4(i4 8, i4 2, i32 2) ; %res = 15 (2 / 0.5 = 4 => 3.75) 16559 16560 16561Specialised Arithmetic Intrinsics 16562--------------------------------- 16563 16564.. _i_intr_llvm_canonicalize: 16565 16566'``llvm.canonicalize.*``' Intrinsic 16567^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16568 16569Syntax: 16570""""""" 16571 16572:: 16573 16574 declare float @llvm.canonicalize.f32(float %a) 16575 declare double @llvm.canonicalize.f64(double %b) 16576 16577Overview: 16578""""""""" 16579 16580The '``llvm.canonicalize.*``' intrinsic returns the platform specific canonical 16581encoding of a floating-point number. This canonicalization is useful for 16582implementing certain numeric primitives such as frexp. The canonical encoding is 16583defined by IEEE-754-2008 to be: 16584 16585:: 16586 16587 2.1.8 canonical encoding: The preferred encoding of a floating-point 16588 representation in a format. Applied to declets, significands of finite 16589 numbers, infinities, and NaNs, especially in decimal formats. 16590 16591This operation can also be considered equivalent to the IEEE-754-2008 16592conversion of a floating-point value to the same format. NaNs are handled 16593according to section 6.2. 16594 16595Examples of non-canonical encodings: 16596 16597- x87 pseudo denormals, pseudo NaNs, pseudo Infinity, Unnormals. These are 16598 converted to a canonical representation per hardware-specific protocol. 16599- Many normal decimal floating-point numbers have non-canonical alternative 16600 encodings. 16601- Some machines, like GPUs or ARMv7 NEON, do not support subnormal values. 16602 These are treated as non-canonical encodings of zero and will be flushed to 16603 a zero of the same sign by this operation. 16604 16605Note that per IEEE-754-2008 6.2, systems that support signaling NaNs with 16606default exception handling must signal an invalid exception, and produce a 16607quiet NaN result. 16608 16609This function should always be implementable as multiplication by 1.0, provided 16610that the compiler does not constant fold the operation. Likewise, division by 166111.0 and ``llvm.minnum(x, x)`` are possible implementations. Addition with 16612-0.0 is also sufficient provided that the rounding mode is not -Infinity. 16613 16614``@llvm.canonicalize`` must preserve the equality relation. That is: 16615 16616- ``(@llvm.canonicalize(x) == x)`` is equivalent to ``(x == x)`` 16617- ``(@llvm.canonicalize(x) == @llvm.canonicalize(y))`` is equivalent to 16618 to ``(x == y)`` 16619 16620Additionally, the sign of zero must be conserved: 16621``@llvm.canonicalize(-0.0) = -0.0`` and ``@llvm.canonicalize(+0.0) = +0.0`` 16622 16623The payload bits of a NaN must be conserved, with two exceptions. 16624First, environments which use only a single canonical representation of NaN 16625must perform said canonicalization. Second, SNaNs must be quieted per the 16626usual methods. 16627 16628The canonicalization operation may be optimized away if: 16629 16630- The input is known to be canonical. For example, it was produced by a 16631 floating-point operation that is required by the standard to be canonical. 16632- The result is consumed only by (or fused with) other floating-point 16633 operations. That is, the bits of the floating-point value are not examined. 16634 16635'``llvm.fmuladd.*``' Intrinsic 16636^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16637 16638Syntax: 16639""""""" 16640 16641:: 16642 16643 declare float @llvm.fmuladd.f32(float %a, float %b, float %c) 16644 declare double @llvm.fmuladd.f64(double %a, double %b, double %c) 16645 16646Overview: 16647""""""""" 16648 16649The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add 16650expressions that can be fused if the code generator determines that (a) the 16651target instruction set has support for a fused operation, and (b) that the 16652fused operation is more efficient than the equivalent, separate pair of mul 16653and add instructions. 16654 16655Arguments: 16656"""""""""" 16657 16658The '``llvm.fmuladd.*``' intrinsics each take three arguments: two 16659multiplicands, a and b, and an addend c. 16660 16661Semantics: 16662"""""""""" 16663 16664The expression: 16665 16666:: 16667 16668 %0 = call float @llvm.fmuladd.f32(%a, %b, %c) 16669 16670is equivalent to the expression a \* b + c, except that it is unspecified 16671whether rounding will be performed between the multiplication and addition 16672steps. Fusion is not guaranteed, even if the target platform supports it. 16673If a fused multiply-add is required, the corresponding 16674:ref:`llvm.fma <int_fma>` intrinsic function should be used instead. 16675This never sets errno, just as '``llvm.fma.*``'. 16676 16677Examples: 16678""""""""" 16679 16680.. code-block:: llvm 16681 16682 %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c 16683 16684 16685Hardware-Loop Intrinsics 16686------------------------ 16687 16688LLVM support several intrinsics to mark a loop as a hardware-loop. They are 16689hints to the backend which are required to lower these intrinsics further to target 16690specific instructions, or revert the hardware-loop to a normal loop if target 16691specific restriction are not met and a hardware-loop can't be generated. 16692 16693These intrinsics may be modified in the future and are not intended to be used 16694outside the backend. Thus, front-end and mid-level optimizations should not be 16695generating these intrinsics. 16696 16697 16698'``llvm.set.loop.iterations.*``' Intrinsic 16699^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16700 16701Syntax: 16702""""""" 16703 16704This is an overloaded intrinsic. 16705 16706:: 16707 16708 declare void @llvm.set.loop.iterations.i32(i32) 16709 declare void @llvm.set.loop.iterations.i64(i64) 16710 16711Overview: 16712""""""""" 16713 16714The '``llvm.set.loop.iterations.*``' intrinsics are used to specify the 16715hardware-loop trip count. They are placed in the loop preheader basic block and 16716are marked as ``IntrNoDuplicate`` to avoid optimizers duplicating these 16717instructions. 16718 16719Arguments: 16720"""""""""" 16721 16722The integer operand is the loop trip count of the hardware-loop, and thus 16723not e.g. the loop back-edge taken count. 16724 16725Semantics: 16726"""""""""" 16727 16728The '``llvm.set.loop.iterations.*``' intrinsics do not perform any arithmetic 16729on their operand. It's a hint to the backend that can use this to set up the 16730hardware-loop count with a target specific instruction, usually a move of this 16731value to a special register or a hardware-loop instruction. 16732 16733 16734'``llvm.start.loop.iterations.*``' Intrinsic 16735^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16736 16737Syntax: 16738""""""" 16739 16740This is an overloaded intrinsic. 16741 16742:: 16743 16744 declare i32 @llvm.start.loop.iterations.i32(i32) 16745 declare i64 @llvm.start.loop.iterations.i64(i64) 16746 16747Overview: 16748""""""""" 16749 16750The '``llvm.start.loop.iterations.*``' intrinsics are similar to the 16751'``llvm.set.loop.iterations.*``' intrinsics, used to specify the 16752hardware-loop trip count but also produce a value identical to the input 16753that can be used as the input to the loop. They are placed in the loop 16754preheader basic block and the output is expected to be the input to the 16755phi for the induction variable of the loop, decremented by the 16756'``llvm.loop.decrement.reg.*``'. 16757 16758Arguments: 16759"""""""""" 16760 16761The integer operand is the loop trip count of the hardware-loop, and thus 16762not e.g. the loop back-edge taken count. 16763 16764Semantics: 16765"""""""""" 16766 16767The '``llvm.start.loop.iterations.*``' intrinsics do not perform any arithmetic 16768on their operand. It's a hint to the backend that can use this to set up the 16769hardware-loop count with a target specific instruction, usually a move of this 16770value to a special register or a hardware-loop instruction. 16771 16772'``llvm.test.set.loop.iterations.*``' Intrinsic 16773^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16774 16775Syntax: 16776""""""" 16777 16778This is an overloaded intrinsic. 16779 16780:: 16781 16782 declare i1 @llvm.test.set.loop.iterations.i32(i32) 16783 declare i1 @llvm.test.set.loop.iterations.i64(i64) 16784 16785Overview: 16786""""""""" 16787 16788The '``llvm.test.set.loop.iterations.*``' intrinsics are used to specify the 16789the loop trip count, and also test that the given count is not zero, allowing 16790it to control entry to a while-loop. They are placed in the loop preheader's 16791predecessor basic block, and are marked as ``IntrNoDuplicate`` to avoid 16792optimizers duplicating these instructions. 16793 16794Arguments: 16795"""""""""" 16796 16797The integer operand is the loop trip count of the hardware-loop, and thus 16798not e.g. the loop back-edge taken count. 16799 16800Semantics: 16801"""""""""" 16802 16803The '``llvm.test.set.loop.iterations.*``' intrinsics do not perform any 16804arithmetic on their operand. It's a hint to the backend that can use this to 16805set up the hardware-loop count with a target specific instruction, usually a 16806move of this value to a special register or a hardware-loop instruction. 16807The result is the conditional value of whether the given count is not zero. 16808 16809 16810'``llvm.test.start.loop.iterations.*``' Intrinsic 16811^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16812 16813Syntax: 16814""""""" 16815 16816This is an overloaded intrinsic. 16817 16818:: 16819 16820 declare {i32, i1} @llvm.test.start.loop.iterations.i32(i32) 16821 declare {i64, i1} @llvm.test.start.loop.iterations.i64(i64) 16822 16823Overview: 16824""""""""" 16825 16826The '``llvm.test.start.loop.iterations.*``' intrinsics are similar to the 16827'``llvm.test.set.loop.iterations.*``' and '``llvm.start.loop.iterations.*``' 16828intrinsics, used to specify the hardware-loop trip count, but also produce a 16829value identical to the input that can be used as the input to the loop. The 16830second i1 output controls entry to a while-loop. 16831 16832Arguments: 16833"""""""""" 16834 16835The integer operand is the loop trip count of the hardware-loop, and thus 16836not e.g. the loop back-edge taken count. 16837 16838Semantics: 16839"""""""""" 16840 16841The '``llvm.test.start.loop.iterations.*``' intrinsics do not perform any 16842arithmetic on their operand. It's a hint to the backend that can use this to 16843set up the hardware-loop count with a target specific instruction, usually a 16844move of this value to a special register or a hardware-loop instruction. 16845The result is a pair of the input and a conditional value of whether the 16846given count is not zero. 16847 16848 16849'``llvm.loop.decrement.reg.*``' Intrinsic 16850^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16851 16852Syntax: 16853""""""" 16854 16855This is an overloaded intrinsic. 16856 16857:: 16858 16859 declare i32 @llvm.loop.decrement.reg.i32(i32, i32) 16860 declare i64 @llvm.loop.decrement.reg.i64(i64, i64) 16861 16862Overview: 16863""""""""" 16864 16865The '``llvm.loop.decrement.reg.*``' intrinsics are used to lower the loop 16866iteration counter and return an updated value that will be used in the next 16867loop test check. 16868 16869Arguments: 16870"""""""""" 16871 16872Both arguments must have identical integer types. The first operand is the 16873loop iteration counter. The second operand is the maximum number of elements 16874processed in an iteration. 16875 16876Semantics: 16877"""""""""" 16878 16879The '``llvm.loop.decrement.reg.*``' intrinsics do an integer ``SUB`` of its 16880two operands, which is not allowed to wrap. They return the remaining number of 16881iterations still to be executed, and can be used together with a ``PHI``, 16882``ICMP`` and ``BR`` to control the number of loop iterations executed. Any 16883optimisations are allowed to treat it is a ``SUB``, and it is supported by 16884SCEV, so it's the backends responsibility to handle cases where it may be 16885optimised. These intrinsics are marked as ``IntrNoDuplicate`` to avoid 16886optimizers duplicating these instructions. 16887 16888 16889'``llvm.loop.decrement.*``' Intrinsic 16890^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16891 16892Syntax: 16893""""""" 16894 16895This is an overloaded intrinsic. 16896 16897:: 16898 16899 declare i1 @llvm.loop.decrement.i32(i32) 16900 declare i1 @llvm.loop.decrement.i64(i64) 16901 16902Overview: 16903""""""""" 16904 16905The HardwareLoops pass allows the loop decrement value to be specified with an 16906option. It defaults to a loop decrement value of 1, but it can be an unsigned 16907integer value provided by this option. The '``llvm.loop.decrement.*``' 16908intrinsics decrement the loop iteration counter with this value, and return a 16909false predicate if the loop should exit, and true otherwise. 16910This is emitted if the loop counter is not updated via a ``PHI`` node, which 16911can also be controlled with an option. 16912 16913Arguments: 16914"""""""""" 16915 16916The integer argument is the loop decrement value used to decrement the loop 16917iteration counter. 16918 16919Semantics: 16920"""""""""" 16921 16922The '``llvm.loop.decrement.*``' intrinsics do a ``SUB`` of the loop iteration 16923counter with the given loop decrement value, and return false if the loop 16924should exit, this ``SUB`` is not allowed to wrap. The result is a condition 16925that is used by the conditional branch controlling the loop. 16926 16927 16928Vector Reduction Intrinsics 16929--------------------------- 16930 16931Horizontal reductions of vectors can be expressed using the following 16932intrinsics. Each one takes a vector operand as an input and applies its 16933respective operation across all elements of the vector, returning a single 16934scalar result of the same element type. 16935 16936.. _int_vector_reduce_add: 16937 16938'``llvm.vector.reduce.add.*``' Intrinsic 16939^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16940 16941Syntax: 16942""""""" 16943 16944:: 16945 16946 declare i32 @llvm.vector.reduce.add.v4i32(<4 x i32> %a) 16947 declare i64 @llvm.vector.reduce.add.v2i64(<2 x i64> %a) 16948 16949Overview: 16950""""""""" 16951 16952The '``llvm.vector.reduce.add.*``' intrinsics do an integer ``ADD`` 16953reduction of a vector, returning the result as a scalar. The return type matches 16954the element-type of the vector input. 16955 16956Arguments: 16957"""""""""" 16958The argument to this intrinsic must be a vector of integer values. 16959 16960.. _int_vector_reduce_fadd: 16961 16962'``llvm.vector.reduce.fadd.*``' Intrinsic 16963^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 16964 16965Syntax: 16966""""""" 16967 16968:: 16969 16970 declare float @llvm.vector.reduce.fadd.v4f32(float %start_value, <4 x float> %a) 16971 declare double @llvm.vector.reduce.fadd.v2f64(double %start_value, <2 x double> %a) 16972 16973Overview: 16974""""""""" 16975 16976The '``llvm.vector.reduce.fadd.*``' intrinsics do a floating-point 16977``ADD`` reduction of a vector, returning the result as a scalar. The return type 16978matches the element-type of the vector input. 16979 16980If the intrinsic call has the 'reassoc' flag set, then the reduction will not 16981preserve the associativity of an equivalent scalarized counterpart. Otherwise 16982the reduction will be *sequential*, thus implying that the operation respects 16983the associativity of a scalarized reduction. That is, the reduction begins with 16984the start value and performs an fadd operation with consecutively increasing 16985vector element indices. See the following pseudocode: 16986 16987:: 16988 16989 float sequential_fadd(start_value, input_vector) 16990 result = start_value 16991 for i = 0 to length(input_vector) 16992 result = result + input_vector[i] 16993 return result 16994 16995 16996Arguments: 16997"""""""""" 16998The first argument to this intrinsic is a scalar start value for the reduction. 16999The type of the start value matches the element-type of the vector input. 17000The second argument must be a vector of floating-point values. 17001 17002To ignore the start value, negative zero (``-0.0``) can be used, as it is 17003the neutral value of floating point addition. 17004 17005Examples: 17006""""""""" 17007 17008:: 17009 17010 %unord = call reassoc float @llvm.vector.reduce.fadd.v4f32(float -0.0, <4 x float> %input) ; relaxed reduction 17011 %ord = call float @llvm.vector.reduce.fadd.v4f32(float %start_value, <4 x float> %input) ; sequential reduction 17012 17013 17014.. _int_vector_reduce_mul: 17015 17016'``llvm.vector.reduce.mul.*``' Intrinsic 17017^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17018 17019Syntax: 17020""""""" 17021 17022:: 17023 17024 declare i32 @llvm.vector.reduce.mul.v4i32(<4 x i32> %a) 17025 declare i64 @llvm.vector.reduce.mul.v2i64(<2 x i64> %a) 17026 17027Overview: 17028""""""""" 17029 17030The '``llvm.vector.reduce.mul.*``' intrinsics do an integer ``MUL`` 17031reduction of a vector, returning the result as a scalar. The return type matches 17032the element-type of the vector input. 17033 17034Arguments: 17035"""""""""" 17036The argument to this intrinsic must be a vector of integer values. 17037 17038.. _int_vector_reduce_fmul: 17039 17040'``llvm.vector.reduce.fmul.*``' Intrinsic 17041^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17042 17043Syntax: 17044""""""" 17045 17046:: 17047 17048 declare float @llvm.vector.reduce.fmul.v4f32(float %start_value, <4 x float> %a) 17049 declare double @llvm.vector.reduce.fmul.v2f64(double %start_value, <2 x double> %a) 17050 17051Overview: 17052""""""""" 17053 17054The '``llvm.vector.reduce.fmul.*``' intrinsics do a floating-point 17055``MUL`` reduction of a vector, returning the result as a scalar. The return type 17056matches the element-type of the vector input. 17057 17058If the intrinsic call has the 'reassoc' flag set, then the reduction will not 17059preserve the associativity of an equivalent scalarized counterpart. Otherwise 17060the reduction will be *sequential*, thus implying that the operation respects 17061the associativity of a scalarized reduction. That is, the reduction begins with 17062the start value and performs an fmul operation with consecutively increasing 17063vector element indices. See the following pseudocode: 17064 17065:: 17066 17067 float sequential_fmul(start_value, input_vector) 17068 result = start_value 17069 for i = 0 to length(input_vector) 17070 result = result * input_vector[i] 17071 return result 17072 17073 17074Arguments: 17075"""""""""" 17076The first argument to this intrinsic is a scalar start value for the reduction. 17077The type of the start value matches the element-type of the vector input. 17078The second argument must be a vector of floating-point values. 17079 17080To ignore the start value, one (``1.0``) can be used, as it is the neutral 17081value of floating point multiplication. 17082 17083Examples: 17084""""""""" 17085 17086:: 17087 17088 %unord = call reassoc float @llvm.vector.reduce.fmul.v4f32(float 1.0, <4 x float> %input) ; relaxed reduction 17089 %ord = call float @llvm.vector.reduce.fmul.v4f32(float %start_value, <4 x float> %input) ; sequential reduction 17090 17091.. _int_vector_reduce_and: 17092 17093'``llvm.vector.reduce.and.*``' Intrinsic 17094^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17095 17096Syntax: 17097""""""" 17098 17099:: 17100 17101 declare i32 @llvm.vector.reduce.and.v4i32(<4 x i32> %a) 17102 17103Overview: 17104""""""""" 17105 17106The '``llvm.vector.reduce.and.*``' intrinsics do a bitwise ``AND`` 17107reduction of a vector, returning the result as a scalar. The return type matches 17108the element-type of the vector input. 17109 17110Arguments: 17111"""""""""" 17112The argument to this intrinsic must be a vector of integer values. 17113 17114.. _int_vector_reduce_or: 17115 17116'``llvm.vector.reduce.or.*``' Intrinsic 17117^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17118 17119Syntax: 17120""""""" 17121 17122:: 17123 17124 declare i32 @llvm.vector.reduce.or.v4i32(<4 x i32> %a) 17125 17126Overview: 17127""""""""" 17128 17129The '``llvm.vector.reduce.or.*``' intrinsics do a bitwise ``OR`` reduction 17130of a vector, returning the result as a scalar. The return type matches the 17131element-type of the vector input. 17132 17133Arguments: 17134"""""""""" 17135The argument to this intrinsic must be a vector of integer values. 17136 17137.. _int_vector_reduce_xor: 17138 17139'``llvm.vector.reduce.xor.*``' Intrinsic 17140^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17141 17142Syntax: 17143""""""" 17144 17145:: 17146 17147 declare i32 @llvm.vector.reduce.xor.v4i32(<4 x i32> %a) 17148 17149Overview: 17150""""""""" 17151 17152The '``llvm.vector.reduce.xor.*``' intrinsics do a bitwise ``XOR`` 17153reduction of a vector, returning the result as a scalar. The return type matches 17154the element-type of the vector input. 17155 17156Arguments: 17157"""""""""" 17158The argument to this intrinsic must be a vector of integer values. 17159 17160.. _int_vector_reduce_smax: 17161 17162'``llvm.vector.reduce.smax.*``' Intrinsic 17163^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17164 17165Syntax: 17166""""""" 17167 17168:: 17169 17170 declare i32 @llvm.vector.reduce.smax.v4i32(<4 x i32> %a) 17171 17172Overview: 17173""""""""" 17174 17175The '``llvm.vector.reduce.smax.*``' intrinsics do a signed integer 17176``MAX`` reduction of a vector, returning the result as a scalar. The return type 17177matches the element-type of the vector input. 17178 17179Arguments: 17180"""""""""" 17181The argument to this intrinsic must be a vector of integer values. 17182 17183.. _int_vector_reduce_smin: 17184 17185'``llvm.vector.reduce.smin.*``' Intrinsic 17186^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17187 17188Syntax: 17189""""""" 17190 17191:: 17192 17193 declare i32 @llvm.vector.reduce.smin.v4i32(<4 x i32> %a) 17194 17195Overview: 17196""""""""" 17197 17198The '``llvm.vector.reduce.smin.*``' intrinsics do a signed integer 17199``MIN`` reduction of a vector, returning the result as a scalar. The return type 17200matches the element-type of the vector input. 17201 17202Arguments: 17203"""""""""" 17204The argument to this intrinsic must be a vector of integer values. 17205 17206.. _int_vector_reduce_umax: 17207 17208'``llvm.vector.reduce.umax.*``' Intrinsic 17209^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17210 17211Syntax: 17212""""""" 17213 17214:: 17215 17216 declare i32 @llvm.vector.reduce.umax.v4i32(<4 x i32> %a) 17217 17218Overview: 17219""""""""" 17220 17221The '``llvm.vector.reduce.umax.*``' intrinsics do an unsigned 17222integer ``MAX`` reduction of a vector, returning the result as a scalar. The 17223return type matches the element-type of the vector input. 17224 17225Arguments: 17226"""""""""" 17227The argument to this intrinsic must be a vector of integer values. 17228 17229.. _int_vector_reduce_umin: 17230 17231'``llvm.vector.reduce.umin.*``' Intrinsic 17232^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17233 17234Syntax: 17235""""""" 17236 17237:: 17238 17239 declare i32 @llvm.vector.reduce.umin.v4i32(<4 x i32> %a) 17240 17241Overview: 17242""""""""" 17243 17244The '``llvm.vector.reduce.umin.*``' intrinsics do an unsigned 17245integer ``MIN`` reduction of a vector, returning the result as a scalar. The 17246return type matches the element-type of the vector input. 17247 17248Arguments: 17249"""""""""" 17250The argument to this intrinsic must be a vector of integer values. 17251 17252.. _int_vector_reduce_fmax: 17253 17254'``llvm.vector.reduce.fmax.*``' Intrinsic 17255^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17256 17257Syntax: 17258""""""" 17259 17260:: 17261 17262 declare float @llvm.vector.reduce.fmax.v4f32(<4 x float> %a) 17263 declare double @llvm.vector.reduce.fmax.v2f64(<2 x double> %a) 17264 17265Overview: 17266""""""""" 17267 17268The '``llvm.vector.reduce.fmax.*``' intrinsics do a floating-point 17269``MAX`` reduction of a vector, returning the result as a scalar. The return type 17270matches the element-type of the vector input. 17271 17272This instruction has the same comparison semantics as the '``llvm.maxnum.*``' 17273intrinsic. That is, the result will always be a number unless all elements of 17274the vector are NaN. For a vector with maximum element magnitude 0.0 and 17275containing both +0.0 and -0.0 elements, the sign of the result is unspecified. 17276 17277If the intrinsic call has the ``nnan`` fast-math flag, then the operation can 17278assume that NaNs are not present in the input vector. 17279 17280Arguments: 17281"""""""""" 17282The argument to this intrinsic must be a vector of floating-point values. 17283 17284.. _int_vector_reduce_fmin: 17285 17286'``llvm.vector.reduce.fmin.*``' Intrinsic 17287^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17288 17289Syntax: 17290""""""" 17291This is an overloaded intrinsic. 17292 17293:: 17294 17295 declare float @llvm.vector.reduce.fmin.v4f32(<4 x float> %a) 17296 declare double @llvm.vector.reduce.fmin.v2f64(<2 x double> %a) 17297 17298Overview: 17299""""""""" 17300 17301The '``llvm.vector.reduce.fmin.*``' intrinsics do a floating-point 17302``MIN`` reduction of a vector, returning the result as a scalar. The return type 17303matches the element-type of the vector input. 17304 17305This instruction has the same comparison semantics as the '``llvm.minnum.*``' 17306intrinsic. That is, the result will always be a number unless all elements of 17307the vector are NaN. For a vector with minimum element magnitude 0.0 and 17308containing both +0.0 and -0.0 elements, the sign of the result is unspecified. 17309 17310If the intrinsic call has the ``nnan`` fast-math flag, then the operation can 17311assume that NaNs are not present in the input vector. 17312 17313Arguments: 17314"""""""""" 17315The argument to this intrinsic must be a vector of floating-point values. 17316 17317'``llvm.vector.insert``' Intrinsic 17318^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17319 17320Syntax: 17321""""""" 17322This is an overloaded intrinsic. 17323 17324:: 17325 17326 ; Insert fixed type into scalable type 17327 declare <vscale x 4 x float> @llvm.vector.insert.nxv4f32.v4f32(<vscale x 4 x float> %vec, <4 x float> %subvec, i64 <idx>) 17328 declare <vscale x 2 x double> @llvm.vector.insert.nxv2f64.v2f64(<vscale x 2 x double> %vec, <2 x double> %subvec, i64 <idx>) 17329 17330 ; Insert scalable type into scalable type 17331 declare <vscale x 4 x float> @llvm.vector.insert.nxv4f64.nxv2f64(<vscale x 4 x float> %vec, <vscale x 2 x float> %subvec, i64 <idx>) 17332 17333 ; Insert fixed type into fixed type 17334 declare <4 x double> @llvm.vector.insert.v4f64.v2f64(<4 x double> %vec, <2 x double> %subvec, i64 <idx>) 17335 17336Overview: 17337""""""""" 17338 17339The '``llvm.vector.insert.*``' intrinsics insert a vector into another vector 17340starting from a given index. The return type matches the type of the vector we 17341insert into. Conceptually, this can be used to build a scalable vector out of 17342non-scalable vectors, however this intrinsic can also be used on purely fixed 17343types. 17344 17345Scalable vectors can only be inserted into other scalable vectors. 17346 17347Arguments: 17348"""""""""" 17349 17350The ``vec`` is the vector which ``subvec`` will be inserted into. 17351The ``subvec`` is the vector that will be inserted. 17352 17353``idx`` represents the starting element number at which ``subvec`` will be 17354inserted. ``idx`` must be a constant multiple of ``subvec``'s known minimum 17355vector length. If ``subvec`` is a scalable vector, ``idx`` is first scaled by 17356the runtime scaling factor of ``subvec``. The elements of ``vec`` starting at 17357``idx`` are overwritten with ``subvec``. Elements ``idx`` through (``idx`` + 17358num_elements(``subvec``) - 1) must be valid ``vec`` indices. If this condition 17359cannot be determined statically but is false at runtime, then the result vector 17360is a :ref:`poison value <poisonvalues>`. 17361 17362 17363'``llvm.vector.extract``' Intrinsic 17364^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17365 17366Syntax: 17367""""""" 17368This is an overloaded intrinsic. 17369 17370:: 17371 17372 ; Extract fixed type from scalable type 17373 declare <4 x float> @llvm.vector.extract.v4f32.nxv4f32(<vscale x 4 x float> %vec, i64 <idx>) 17374 declare <2 x double> @llvm.vector.extract.v2f64.nxv2f64(<vscale x 2 x double> %vec, i64 <idx>) 17375 17376 ; Extract scalable type from scalable type 17377 declare <vscale x 2 x float> @llvm.vector.extract.nxv2f32.nxv4f32(<vscale x 4 x float> %vec, i64 <idx>) 17378 17379 ; Extract fixed type from fixed type 17380 declare <2 x double> @llvm.vector.extract.v2f64.v4f64(<4 x double> %vec, i64 <idx>) 17381 17382Overview: 17383""""""""" 17384 17385The '``llvm.vector.extract.*``' intrinsics extract a vector from within another 17386vector starting from a given index. The return type must be explicitly 17387specified. Conceptually, this can be used to decompose a scalable vector into 17388non-scalable parts, however this intrinsic can also be used on purely fixed 17389types. 17390 17391Scalable vectors can only be extracted from other scalable vectors. 17392 17393Arguments: 17394"""""""""" 17395 17396The ``vec`` is the vector from which we will extract a subvector. 17397 17398The ``idx`` specifies the starting element number within ``vec`` from which a 17399subvector is extracted. ``idx`` must be a constant multiple of the known-minimum 17400vector length of the result type. If the result type is a scalable vector, 17401``idx`` is first scaled by the result type's runtime scaling factor. Elements 17402``idx`` through (``idx`` + num_elements(result_type) - 1) must be valid vector 17403indices. If this condition cannot be determined statically but is false at 17404runtime, then the result vector is a :ref:`poison value <poisonvalues>`. The 17405``idx`` parameter must be a vector index constant type (for most targets this 17406will be an integer pointer type). 17407 17408'``llvm.experimental.vector.reverse``' Intrinsic 17409^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17410 17411Syntax: 17412""""""" 17413This is an overloaded intrinsic. 17414 17415:: 17416 17417 declare <2 x i8> @llvm.experimental.vector.reverse.v2i8(<2 x i8> %a) 17418 declare <vscale x 4 x i32> @llvm.experimental.vector.reverse.nxv4i32(<vscale x 4 x i32> %a) 17419 17420Overview: 17421""""""""" 17422 17423The '``llvm.experimental.vector.reverse.*``' intrinsics reverse a vector. 17424The intrinsic takes a single vector and returns a vector of matching type but 17425with the original lane order reversed. These intrinsics work for both fixed 17426and scalable vectors. While this intrinsic is marked as experimental the 17427recommended way to express reverse operations for fixed-width vectors is still 17428to use a shufflevector, as that may allow for more optimization opportunities. 17429 17430Arguments: 17431"""""""""" 17432 17433The argument to this intrinsic must be a vector. 17434 17435'``llvm.experimental.vector.splice``' Intrinsic 17436^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17437 17438Syntax: 17439""""""" 17440This is an overloaded intrinsic. 17441 17442:: 17443 17444 declare <2 x double> @llvm.experimental.vector.splice.v2f64(<2 x double> %vec1, <2 x double> %vec2, i32 %imm) 17445 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) 17446 17447Overview: 17448""""""""" 17449 17450The '``llvm.experimental.vector.splice.*``' intrinsics construct a vector by 17451concatenating elements from the first input vector with elements of the second 17452input vector, returning a vector of the same type as the input vectors. The 17453signed immediate, modulo the number of elements in the vector, is the index 17454into the first vector from which to extract the result value. This means 17455conceptually that for a positive immediate, a vector is extracted from 17456``concat(%vec1, %vec2)`` starting at index ``imm``, whereas for a negative 17457immediate, it extracts ``-imm`` trailing elements from the first vector, and 17458the remaining elements from ``%vec2``. 17459 17460These intrinsics work for both fixed and scalable vectors. While this intrinsic 17461is marked as experimental, the recommended way to express this operation for 17462fixed-width vectors is still to use a shufflevector, as that may allow for more 17463optimization opportunities. 17464 17465For example: 17466 17467.. code-block:: text 17468 17469 llvm.experimental.vector.splice(<A,B,C,D>, <E,F,G,H>, 1) ==> <B, C, D, E> ; index 17470 llvm.experimental.vector.splice(<A,B,C,D>, <E,F,G,H>, -3) ==> <B, C, D, E> ; trailing elements 17471 17472 17473Arguments: 17474"""""""""" 17475 17476The first two operands are vectors with the same type. The start index is imm 17477modulo the runtime number of elements in the source vector. For a fixed-width 17478vector <N x eltty>, imm is a signed integer constant in the range 17479-N <= imm < N. For a scalable vector <vscale x N x eltty>, imm is a signed 17480integer constant in the range -X <= imm < X where X=vscale_range_min * N. 17481 17482'``llvm.experimental.stepvector``' Intrinsic 17483^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17484 17485This is an overloaded intrinsic. You can use ``llvm.experimental.stepvector`` 17486to generate a vector whose lane values comprise the linear sequence 17487<0, 1, 2, ...>. It is primarily intended for scalable vectors. 17488 17489:: 17490 17491 declare <vscale x 4 x i32> @llvm.experimental.stepvector.nxv4i32() 17492 declare <vscale x 8 x i16> @llvm.experimental.stepvector.nxv8i16() 17493 17494The '``llvm.experimental.stepvector``' intrinsics are used to create vectors 17495of integers whose elements contain a linear sequence of values starting from 0 17496with a step of 1. This experimental intrinsic can only be used for vectors 17497with integer elements that are at least 8 bits in size. If the sequence value 17498exceeds the allowed limit for the element type then the result for that lane is 17499undefined. 17500 17501These intrinsics work for both fixed and scalable vectors. While this intrinsic 17502is marked as experimental, the recommended way to express this operation for 17503fixed-width vectors is still to generate a constant vector instead. 17504 17505 17506Arguments: 17507"""""""""" 17508 17509None. 17510 17511 17512Matrix Intrinsics 17513----------------- 17514 17515Operations on matrixes requiring shape information (like number of rows/columns 17516or the memory layout) can be expressed using the matrix intrinsics. These 17517intrinsics require matrix dimensions to be passed as immediate arguments, and 17518matrixes are passed and returned as vectors. This means that for a ``R`` x 17519``C`` matrix, element ``i`` of column ``j`` is at index ``j * R + i`` in the 17520corresponding vector, with indices starting at 0. Currently column-major layout 17521is assumed. The intrinsics support both integer and floating point matrixes. 17522 17523 17524'``llvm.matrix.transpose.*``' Intrinsic 17525^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17526 17527Syntax: 17528""""""" 17529This is an overloaded intrinsic. 17530 17531:: 17532 17533 declare vectorty @llvm.matrix.transpose.*(vectorty %In, i32 <Rows>, i32 <Cols>) 17534 17535Overview: 17536""""""""" 17537 17538The '``llvm.matrix.transpose.*``' intrinsics treat ``%In`` as a ``<Rows> x 17539<Cols>`` matrix and return the transposed matrix in the result vector. 17540 17541Arguments: 17542"""""""""" 17543 17544The first argument ``%In`` is a vector that corresponds to a ``<Rows> x 17545<Cols>`` matrix. Thus, arguments ``<Rows>`` and ``<Cols>`` correspond to the 17546number of rows and columns, respectively, and must be positive, constant 17547integers. The returned vector must have ``<Rows> * <Cols>`` elements, and have 17548the same float or integer element type as ``%In``. 17549 17550'``llvm.matrix.multiply.*``' Intrinsic 17551^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17552 17553Syntax: 17554""""""" 17555This is an overloaded intrinsic. 17556 17557:: 17558 17559 declare vectorty @llvm.matrix.multiply.*(vectorty %A, vectorty %B, i32 <OuterRows>, i32 <Inner>, i32 <OuterColumns>) 17560 17561Overview: 17562""""""""" 17563 17564The '``llvm.matrix.multiply.*``' intrinsics treat ``%A`` as a ``<OuterRows> x 17565<Inner>`` matrix, ``%B`` as a ``<Inner> x <OuterColumns>`` matrix, and 17566multiplies them. The result matrix is returned in the result vector. 17567 17568Arguments: 17569"""""""""" 17570 17571The first vector argument ``%A`` corresponds to a matrix with ``<OuterRows> * 17572<Inner>`` elements, and the second argument ``%B`` to a matrix with 17573``<Inner> * <OuterColumns>`` elements. Arguments ``<OuterRows>``, 17574``<Inner>`` and ``<OuterColumns>`` must be positive, constant integers. The 17575returned vector must have ``<OuterRows> * <OuterColumns>`` elements. 17576Vectors ``%A``, ``%B``, and the returned vector all have the same float or 17577integer element type. 17578 17579 17580'``llvm.matrix.column.major.load.*``' Intrinsic 17581^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17582 17583Syntax: 17584""""""" 17585This is an overloaded intrinsic. 17586 17587:: 17588 17589 declare vectorty @llvm.matrix.column.major.load.*( 17590 ptrty %Ptr, i64 %Stride, i1 <IsVolatile>, i32 <Rows>, i32 <Cols>) 17591 17592Overview: 17593""""""""" 17594 17595The '``llvm.matrix.column.major.load.*``' intrinsics load a ``<Rows> x <Cols>`` 17596matrix using a stride of ``%Stride`` to compute the start address of the 17597different columns. The offset is computed using ``%Stride``'s bitwidth. This 17598allows for convenient loading of sub matrixes. If ``<IsVolatile>`` is true, the 17599intrinsic is considered a :ref:`volatile memory access <volatile>`. The result 17600matrix is returned in the result vector. If the ``%Ptr`` argument is known to 17601be aligned to some boundary, this can be specified as an attribute on the 17602argument. 17603 17604Arguments: 17605"""""""""" 17606 17607The first argument ``%Ptr`` is a pointer type to the returned vector type, and 17608corresponds to the start address to load from. The second argument ``%Stride`` 17609is a positive, constant integer with ``%Stride >= <Rows>``. ``%Stride`` is used 17610to compute the column memory addresses. I.e., for a column ``C``, its start 17611memory addresses is calculated with ``%Ptr + C * %Stride``. The third Argument 17612``<IsVolatile>`` is a boolean value. The fourth and fifth arguments, 17613``<Rows>`` and ``<Cols>``, correspond to the number of rows and columns, 17614respectively, and must be positive, constant integers. The returned vector must 17615have ``<Rows> * <Cols>`` elements. 17616 17617The :ref:`align <attr_align>` parameter attribute can be provided for the 17618``%Ptr`` arguments. 17619 17620 17621'``llvm.matrix.column.major.store.*``' Intrinsic 17622^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17623 17624Syntax: 17625""""""" 17626 17627:: 17628 17629 declare void @llvm.matrix.column.major.store.*( 17630 vectorty %In, ptrty %Ptr, i64 %Stride, i1 <IsVolatile>, i32 <Rows>, i32 <Cols>) 17631 17632Overview: 17633""""""""" 17634 17635The '``llvm.matrix.column.major.store.*``' intrinsics store the ``<Rows> x 17636<Cols>`` matrix in ``%In`` to memory using a stride of ``%Stride`` between 17637columns. The offset is computed using ``%Stride``'s bitwidth. If 17638``<IsVolatile>`` is true, the intrinsic is considered a 17639:ref:`volatile memory access <volatile>`. 17640 17641If the ``%Ptr`` argument is known to be aligned to some boundary, this can be 17642specified as an attribute on the argument. 17643 17644Arguments: 17645"""""""""" 17646 17647The first argument ``%In`` is a vector that corresponds to a ``<Rows> x 17648<Cols>`` matrix to be stored to memory. The second argument ``%Ptr`` is a 17649pointer to the vector type of ``%In``, and is the start address of the matrix 17650in memory. The third argument ``%Stride`` is a positive, constant integer with 17651``%Stride >= <Rows>``. ``%Stride`` is used to compute the column memory 17652addresses. I.e., for a column ``C``, its start memory addresses is calculated 17653with ``%Ptr + C * %Stride``. The fourth argument ``<IsVolatile>`` is a boolean 17654value. The arguments ``<Rows>`` and ``<Cols>`` correspond to the number of rows 17655and columns, respectively, and must be positive, constant integers. 17656 17657The :ref:`align <attr_align>` parameter attribute can be provided 17658for the ``%Ptr`` arguments. 17659 17660 17661Half Precision Floating-Point Intrinsics 17662---------------------------------------- 17663 17664For most target platforms, half precision floating-point is a 17665storage-only format. This means that it is a dense encoding (in memory) 17666but does not support computation in the format. 17667 17668This means that code must first load the half-precision floating-point 17669value as an i16, then convert it to float with 17670:ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can 17671then be performed on the float value (including extending to double 17672etc). To store the value back to memory, it is first converted to float 17673if needed, then converted to i16 with 17674:ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an 17675i16 value. 17676 17677.. _int_convert_to_fp16: 17678 17679'``llvm.convert.to.fp16``' Intrinsic 17680^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17681 17682Syntax: 17683""""""" 17684 17685:: 17686 17687 declare i16 @llvm.convert.to.fp16.f32(float %a) 17688 declare i16 @llvm.convert.to.fp16.f64(double %a) 17689 17690Overview: 17691""""""""" 17692 17693The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a 17694conventional floating-point type to half precision floating-point format. 17695 17696Arguments: 17697"""""""""" 17698 17699The intrinsic function contains single argument - the value to be 17700converted. 17701 17702Semantics: 17703"""""""""" 17704 17705The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a 17706conventional floating-point format to half precision floating-point format. The 17707return value is an ``i16`` which contains the converted number. 17708 17709Examples: 17710""""""""" 17711 17712.. code-block:: llvm 17713 17714 %res = call i16 @llvm.convert.to.fp16.f32(float %a) 17715 store i16 %res, i16* @x, align 2 17716 17717.. _int_convert_from_fp16: 17718 17719'``llvm.convert.from.fp16``' Intrinsic 17720^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17721 17722Syntax: 17723""""""" 17724 17725:: 17726 17727 declare float @llvm.convert.from.fp16.f32(i16 %a) 17728 declare double @llvm.convert.from.fp16.f64(i16 %a) 17729 17730Overview: 17731""""""""" 17732 17733The '``llvm.convert.from.fp16``' intrinsic function performs a 17734conversion from half precision floating-point format to single precision 17735floating-point format. 17736 17737Arguments: 17738"""""""""" 17739 17740The intrinsic function contains single argument - the value to be 17741converted. 17742 17743Semantics: 17744"""""""""" 17745 17746The '``llvm.convert.from.fp16``' intrinsic function performs a 17747conversion from half single precision floating-point format to single 17748precision floating-point format. The input half-float value is 17749represented by an ``i16`` value. 17750 17751Examples: 17752""""""""" 17753 17754.. code-block:: llvm 17755 17756 %a = load i16, ptr @x, align 2 17757 %res = call float @llvm.convert.from.fp16(i16 %a) 17758 17759Saturating floating-point to integer conversions 17760------------------------------------------------ 17761 17762The ``fptoui`` and ``fptosi`` instructions return a 17763:ref:`poison value <poisonvalues>` if the rounded-towards-zero value is not 17764representable by the result type. These intrinsics provide an alternative 17765conversion, which will saturate towards the smallest and largest representable 17766integer values instead. 17767 17768'``llvm.fptoui.sat.*``' Intrinsic 17769^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17770 17771Syntax: 17772""""""" 17773 17774This is an overloaded intrinsic. You can use ``llvm.fptoui.sat`` on any 17775floating-point argument type and any integer result type, or vectors thereof. 17776Not all targets may support all types, however. 17777 17778:: 17779 17780 declare i32 @llvm.fptoui.sat.i32.f32(float %f) 17781 declare i19 @llvm.fptoui.sat.i19.f64(double %f) 17782 declare <4 x i100> @llvm.fptoui.sat.v4i100.v4f128(<4 x fp128> %f) 17783 17784Overview: 17785""""""""" 17786 17787This intrinsic converts the argument into an unsigned integer using saturating 17788semantics. 17789 17790Arguments: 17791"""""""""" 17792 17793The argument may be any floating-point or vector of floating-point type. The 17794return value may be any integer or vector of integer type. The number of vector 17795elements in argument and return must be the same. 17796 17797Semantics: 17798"""""""""" 17799 17800The conversion to integer is performed subject to the following rules: 17801 17802- If the argument is any NaN, zero is returned. 17803- If the argument is smaller than zero (this includes negative infinity), 17804 zero is returned. 17805- If the argument is larger than the largest representable unsigned integer of 17806 the result type (this includes positive infinity), the largest representable 17807 unsigned integer is returned. 17808- Otherwise, the result of rounding the argument towards zero is returned. 17809 17810Example: 17811"""""""" 17812 17813.. code-block:: text 17814 17815 %a = call i8 @llvm.fptoui.sat.i8.f32(float 123.9) ; yields i8: 123 17816 %b = call i8 @llvm.fptoui.sat.i8.f32(float -5.7) ; yields i8: 0 17817 %c = call i8 @llvm.fptoui.sat.i8.f32(float 377.0) ; yields i8: 255 17818 %d = call i8 @llvm.fptoui.sat.i8.f32(float 0xFFF8000000000000) ; yields i8: 0 17819 17820'``llvm.fptosi.sat.*``' Intrinsic 17821^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17822 17823Syntax: 17824""""""" 17825 17826This is an overloaded intrinsic. You can use ``llvm.fptosi.sat`` on any 17827floating-point argument type and any integer result type, or vectors thereof. 17828Not all targets may support all types, however. 17829 17830:: 17831 17832 declare i32 @llvm.fptosi.sat.i32.f32(float %f) 17833 declare i19 @llvm.fptosi.sat.i19.f64(double %f) 17834 declare <4 x i100> @llvm.fptosi.sat.v4i100.v4f128(<4 x fp128> %f) 17835 17836Overview: 17837""""""""" 17838 17839This intrinsic converts the argument into a signed integer using saturating 17840semantics. 17841 17842Arguments: 17843"""""""""" 17844 17845The argument may be any floating-point or vector of floating-point type. The 17846return value may be any integer or vector of integer type. The number of vector 17847elements in argument and return must be the same. 17848 17849Semantics: 17850"""""""""" 17851 17852The conversion to integer is performed subject to the following rules: 17853 17854- If the argument is any NaN, zero is returned. 17855- If the argument is smaller than the smallest representable signed integer of 17856 the result type (this includes negative infinity), the smallest 17857 representable signed integer is returned. 17858- If the argument is larger than the largest representable signed integer of 17859 the result type (this includes positive infinity), the largest representable 17860 signed integer is returned. 17861- Otherwise, the result of rounding the argument towards zero is returned. 17862 17863Example: 17864"""""""" 17865 17866.. code-block:: text 17867 17868 %a = call i8 @llvm.fptosi.sat.i8.f32(float 23.9) ; yields i8: 23 17869 %b = call i8 @llvm.fptosi.sat.i8.f32(float -130.8) ; yields i8: -128 17870 %c = call i8 @llvm.fptosi.sat.i8.f32(float 999.0) ; yields i8: 127 17871 %d = call i8 @llvm.fptosi.sat.i8.f32(float 0xFFF8000000000000) ; yields i8: 0 17872 17873.. _dbg_intrinsics: 17874 17875Debugger Intrinsics 17876------------------- 17877 17878The LLVM debugger intrinsics (which all start with ``llvm.dbg.`` 17879prefix), are described in the `LLVM Source Level 17880Debugging <SourceLevelDebugging.html#format-common-intrinsics>`_ 17881document. 17882 17883Exception Handling Intrinsics 17884----------------------------- 17885 17886The LLVM exception handling intrinsics (which all start with 17887``llvm.eh.`` prefix), are described in the `LLVM Exception 17888Handling <ExceptionHandling.html#format-common-intrinsics>`_ document. 17889 17890Pointer Authentication Intrinsics 17891--------------------------------- 17892 17893The LLVM pointer authentication intrinsics (which all start with 17894``llvm.ptrauth.`` prefix), are described in the `Pointer Authentication 17895<PointerAuth.html#intrinsics>`_ document. 17896 17897.. _int_trampoline: 17898 17899Trampoline Intrinsics 17900--------------------- 17901 17902These intrinsics make it possible to excise one parameter, marked with 17903the :ref:`nest <nest>` attribute, from a function. The result is a 17904callable function pointer lacking the nest parameter - the caller does 17905not need to provide a value for it. Instead, the value to use is stored 17906in advance in a "trampoline", a block of memory usually allocated on the 17907stack, which also contains code to splice the nest value into the 17908argument list. This is used to implement the GCC nested function address 17909extension. 17910 17911For example, if the function is ``i32 f(ptr nest %c, i32 %x, i32 %y)`` 17912then the resulting function pointer has signature ``i32 (i32, i32)``. 17913It can be created as follows: 17914 17915.. code-block:: llvm 17916 17917 %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 17918 call ptr @llvm.init.trampoline(ptr %tramp, ptr @f, ptr %nval) 17919 %fp = call ptr @llvm.adjust.trampoline(ptr %tramp) 17920 17921The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to 17922``%val = call i32 %f(ptr %nval, i32 %x, i32 %y)``. 17923 17924.. _int_it: 17925 17926'``llvm.init.trampoline``' Intrinsic 17927^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17928 17929Syntax: 17930""""""" 17931 17932:: 17933 17934 declare void @llvm.init.trampoline(ptr <tramp>, ptr <func>, ptr <nval>) 17935 17936Overview: 17937""""""""" 17938 17939This fills the memory pointed to by ``tramp`` with executable code, 17940turning it into a trampoline. 17941 17942Arguments: 17943"""""""""" 17944 17945The ``llvm.init.trampoline`` intrinsic takes three arguments, all 17946pointers. The ``tramp`` argument must point to a sufficiently large and 17947sufficiently aligned block of memory; this memory is written to by the 17948intrinsic. Note that the size and the alignment are target-specific - 17949LLVM currently provides no portable way of determining them, so a 17950front-end that generates this intrinsic needs to have some 17951target-specific knowledge. The ``func`` argument must hold a function. 17952 17953Semantics: 17954"""""""""" 17955 17956The block of memory pointed to by ``tramp`` is filled with target 17957dependent code, turning it into a function. Then ``tramp`` needs to be 17958passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can 17959be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new 17960function's signature is the same as that of ``func`` with any arguments 17961marked with the ``nest`` attribute removed. At most one such ``nest`` 17962argument is allowed, and it must be of pointer type. Calling the new 17963function is equivalent to calling ``func`` with the same argument list, 17964but with ``nval`` used for the missing ``nest`` argument. If, after 17965calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is 17966modified, then the effect of any later call to the returned function 17967pointer is undefined. 17968 17969.. _int_at: 17970 17971'``llvm.adjust.trampoline``' Intrinsic 17972^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 17973 17974Syntax: 17975""""""" 17976 17977:: 17978 17979 declare ptr @llvm.adjust.trampoline(ptr <tramp>) 17980 17981Overview: 17982""""""""" 17983 17984This performs any required machine-specific adjustment to the address of 17985a trampoline (passed as ``tramp``). 17986 17987Arguments: 17988"""""""""" 17989 17990``tramp`` must point to a block of memory which already has trampoline 17991code filled in by a previous call to 17992:ref:`llvm.init.trampoline <int_it>`. 17993 17994Semantics: 17995"""""""""" 17996 17997On some architectures the address of the code to be executed needs to be 17998different than the address where the trampoline is actually stored. This 17999intrinsic returns the executable address corresponding to ``tramp`` 18000after performing the required machine specific adjustments. The pointer 18001returned can then be :ref:`bitcast and executed <int_trampoline>`. 18002 18003 18004.. _int_vp: 18005 18006Vector Predication Intrinsics 18007----------------------------- 18008VP intrinsics are intended for predicated SIMD/vector code. A typical VP 18009operation takes a vector mask and an explicit vector length parameter as in: 18010 18011:: 18012 18013 <W x T> llvm.vp.<opcode>.*(<W x T> %x, <W x T> %y, <W x i1> %mask, i32 %evl) 18014 18015The vector mask parameter (%mask) always has a vector of `i1` type, for example 18016`<32 x i1>`. The explicit vector length parameter always has the type `i32` and 18017is an unsigned integer value. The explicit vector length parameter (%evl) is in 18018the range: 18019 18020:: 18021 18022 0 <= %evl <= W, where W is the number of vector elements 18023 18024Note that for :ref:`scalable vector types <t_vector>` ``W`` is the runtime 18025length of the vector. 18026 18027The VP intrinsic has undefined behavior if ``%evl > W``. The explicit vector 18028length (%evl) creates a mask, %EVLmask, with all elements ``0 <= i < %evl`` set 18029to True, and all other lanes ``%evl <= i < W`` to False. A new mask %M is 18030calculated with an element-wise AND from %mask and %EVLmask: 18031 18032:: 18033 18034 M = %mask AND %EVLmask 18035 18036A vector operation ``<opcode>`` on vectors ``A`` and ``B`` calculates: 18037 18038:: 18039 18040 A <opcode> B = { A[i] <opcode> B[i] M[i] = True, and 18041 { undef otherwise 18042 18043Optimization Hint 18044^^^^^^^^^^^^^^^^^ 18045 18046Some targets, such as AVX512, do not support the %evl parameter in hardware. 18047The use of an effective %evl is discouraged for those targets. The function 18048``TargetTransformInfo::hasActiveVectorLength()`` returns true when the target 18049has native support for %evl. 18050 18051.. _int_vp_select: 18052 18053'``llvm.vp.select.*``' Intrinsics 18054^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18055 18056Syntax: 18057""""""" 18058This is an overloaded intrinsic. 18059 18060:: 18061 18062 declare <16 x i32> @llvm.vp.select.v16i32 (<16 x i1> <condition>, <16 x i32> <on_true>, <16 x i32> <on_false>, i32 <evl>) 18063 declare <vscale x 4 x i64> @llvm.vp.select.nxv4i64 (<vscale x 4 x i1> <condition>, <vscale x 4 x i64> <on_true>, <vscale x 4 x i64> <on_false>, i32 <evl>) 18064 18065Overview: 18066""""""""" 18067 18068The '``llvm.vp.select``' intrinsic is used to choose one value based on a 18069condition vector, without IR-level branching. 18070 18071Arguments: 18072"""""""""" 18073 18074The first operand is a vector of ``i1`` and indicates the condition. The 18075second operand is the value that is selected where the condition vector is 18076true. The third operand is the value that is selected where the condition 18077vector is false. The vectors must be of the same size. The fourth operand is 18078the explicit vector length. 18079 18080#. The optional ``fast-math flags`` marker indicates that the select has one or 18081 more :ref:`fast-math flags <fastmath>`. These are optimization hints to 18082 enable otherwise unsafe floating-point optimizations. Fast-math flags are 18083 only valid for selects that return a floating-point scalar or vector type, 18084 or an array (nested to any depth) of floating-point scalar or vector types. 18085 18086Semantics: 18087"""""""""" 18088 18089The intrinsic selects lanes from the second and third operand depending on a 18090condition vector. 18091 18092All result lanes at positions greater or equal than ``%evl`` are undefined. 18093For all lanes below ``%evl`` where the condition vector is true the lane is 18094taken from the second operand. Otherwise, the lane is taken from the third 18095operand. 18096 18097Example: 18098"""""""" 18099 18100.. code-block:: llvm 18101 18102 %r = call <4 x i32> @llvm.vp.select.v4i32(<4 x i1> %cond, <4 x i32> %on_true, <4 x i32> %on_false, i32 %evl) 18103 18104 ;;; Expansion. 18105 ;; Any result is legal on lanes at and above %evl. 18106 %also.r = select <4 x i1> %cond, <4 x i32> %on_true, <4 x i32> %on_false 18107 18108 18109.. _int_vp_merge: 18110 18111'``llvm.vp.merge.*``' Intrinsics 18112^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18113 18114Syntax: 18115""""""" 18116This is an overloaded intrinsic. 18117 18118:: 18119 18120 declare <16 x i32> @llvm.vp.merge.v16i32 (<16 x i1> <condition>, <16 x i32> <on_true>, <16 x i32> <on_false>, i32 <pivot>) 18121 declare <vscale x 4 x i64> @llvm.vp.merge.nxv4i64 (<vscale x 4 x i1> <condition>, <vscale x 4 x i64> <on_true>, <vscale x 4 x i64> <on_false>, i32 <pivot>) 18122 18123Overview: 18124""""""""" 18125 18126The '``llvm.vp.merge``' intrinsic is used to choose one value based on a 18127condition vector and an index operand, without IR-level branching. 18128 18129Arguments: 18130"""""""""" 18131 18132The first operand is a vector of ``i1`` and indicates the condition. The 18133second operand is the value that is merged where the condition vector is true. 18134The third operand is the value that is selected where the condition vector is 18135false or the lane position is greater equal than the pivot. The fourth operand 18136is the pivot. 18137 18138#. The optional ``fast-math flags`` marker indicates that the merge has one or 18139 more :ref:`fast-math flags <fastmath>`. These are optimization hints to 18140 enable otherwise unsafe floating-point optimizations. Fast-math flags are 18141 only valid for merges that return a floating-point scalar or vector type, 18142 or an array (nested to any depth) of floating-point scalar or vector types. 18143 18144Semantics: 18145"""""""""" 18146 18147The intrinsic selects lanes from the second and third operand depending on a 18148condition vector and pivot value. 18149 18150For all lanes where the condition vector is true and the lane position is less 18151than ``%pivot`` the lane is taken from the second operand. Otherwise, the lane 18152is taken from the third operand. 18153 18154Example: 18155"""""""" 18156 18157.. code-block:: llvm 18158 18159 %r = call <4 x i32> @llvm.vp.merge.v4i32(<4 x i1> %cond, <4 x i32> %on_true, <4 x i32> %on_false, i32 %pivot) 18160 18161 ;;; Expansion. 18162 ;; Lanes at and above %pivot are taken from %on_false 18163 %atfirst = insertelement <4 x i32> undef, i32 %pivot, i32 0 18164 %splat = shufflevector <4 x i32> %atfirst, <4 x i32> poison, <4 x i32> zeroinitializer 18165 %pivotmask = icmp ult <4 x i32> <i32 0, i32 1, i32 2, i32 3>, <4 x i32> %splat 18166 %mergemask = and <4 x i1> %cond, <4 x i1> %pivotmask 18167 %also.r = select <4 x i1> %mergemask, <4 x i32> %on_true, <4 x i32> %on_false 18168 18169 18170 18171.. _int_vp_add: 18172 18173'``llvm.vp.add.*``' Intrinsics 18174^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18175 18176Syntax: 18177""""""" 18178This is an overloaded intrinsic. 18179 18180:: 18181 18182 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>) 18183 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>) 18184 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>) 18185 18186Overview: 18187""""""""" 18188 18189Predicated integer addition of two vectors of integers. 18190 18191 18192Arguments: 18193"""""""""" 18194 18195The first two operands and the result have the same vector of integer type. The 18196third operand is the vector mask and has the same number of elements as the 18197result vector type. The fourth operand is the explicit vector length of the 18198operation. 18199 18200Semantics: 18201"""""""""" 18202 18203The '``llvm.vp.add``' intrinsic performs integer addition (:ref:`add <i_add>`) 18204of the first and second vector operand on each enabled lane. The result on 18205disabled lanes is undefined. 18206 18207Examples: 18208""""""""" 18209 18210.. code-block:: llvm 18211 18212 %r = call <4 x i32> @llvm.vp.add.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18213 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18214 18215 %t = add <4 x i32> %a, %b 18216 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18217 18218.. _int_vp_sub: 18219 18220'``llvm.vp.sub.*``' Intrinsics 18221^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18222 18223Syntax: 18224""""""" 18225This is an overloaded intrinsic. 18226 18227:: 18228 18229 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>) 18230 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>) 18231 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>) 18232 18233Overview: 18234""""""""" 18235 18236Predicated integer subtraction of two vectors of integers. 18237 18238 18239Arguments: 18240"""""""""" 18241 18242The first two operands and the result have the same vector of integer type. The 18243third operand is the vector mask and has the same number of elements as the 18244result vector type. The fourth operand is the explicit vector length of the 18245operation. 18246 18247Semantics: 18248"""""""""" 18249 18250The '``llvm.vp.sub``' intrinsic performs integer subtraction 18251(:ref:`sub <i_sub>`) of the first and second vector operand on each enabled 18252lane. The result on disabled lanes is undefined. 18253 18254Examples: 18255""""""""" 18256 18257.. code-block:: llvm 18258 18259 %r = call <4 x i32> @llvm.vp.sub.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18260 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18261 18262 %t = sub <4 x i32> %a, %b 18263 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18264 18265 18266 18267.. _int_vp_mul: 18268 18269'``llvm.vp.mul.*``' Intrinsics 18270^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18271 18272Syntax: 18273""""""" 18274This is an overloaded intrinsic. 18275 18276:: 18277 18278 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>) 18279 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>) 18280 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>) 18281 18282Overview: 18283""""""""" 18284 18285Predicated integer multiplication of two vectors of integers. 18286 18287 18288Arguments: 18289"""""""""" 18290 18291The first two operands and the result have the same vector of integer type. The 18292third operand is the vector mask and has the same number of elements as the 18293result vector type. The fourth operand is the explicit vector length of the 18294operation. 18295 18296Semantics: 18297"""""""""" 18298The '``llvm.vp.mul``' intrinsic performs integer multiplication 18299(:ref:`mul <i_mul>`) of the first and second vector operand on each enabled 18300lane. The result on disabled lanes is undefined. 18301 18302Examples: 18303""""""""" 18304 18305.. code-block:: llvm 18306 18307 %r = call <4 x i32> @llvm.vp.mul.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18308 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18309 18310 %t = mul <4 x i32> %a, %b 18311 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18312 18313 18314.. _int_vp_sdiv: 18315 18316'``llvm.vp.sdiv.*``' Intrinsics 18317^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18318 18319Syntax: 18320""""""" 18321This is an overloaded intrinsic. 18322 18323:: 18324 18325 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>) 18326 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>) 18327 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>) 18328 18329Overview: 18330""""""""" 18331 18332Predicated, signed division of two vectors of integers. 18333 18334 18335Arguments: 18336"""""""""" 18337 18338The first two operands and the result have the same vector of integer type. The 18339third operand is the vector mask and has the same number of elements as the 18340result vector type. The fourth operand is the explicit vector length of the 18341operation. 18342 18343Semantics: 18344"""""""""" 18345 18346The '``llvm.vp.sdiv``' intrinsic performs signed division (:ref:`sdiv <i_sdiv>`) 18347of the first and second vector operand on each enabled lane. The result on 18348disabled lanes is undefined. 18349 18350Examples: 18351""""""""" 18352 18353.. code-block:: llvm 18354 18355 %r = call <4 x i32> @llvm.vp.sdiv.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18356 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18357 18358 %t = sdiv <4 x i32> %a, %b 18359 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18360 18361 18362.. _int_vp_udiv: 18363 18364'``llvm.vp.udiv.*``' Intrinsics 18365^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18366 18367Syntax: 18368""""""" 18369This is an overloaded intrinsic. 18370 18371:: 18372 18373 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>) 18374 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>) 18375 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>) 18376 18377Overview: 18378""""""""" 18379 18380Predicated, unsigned division of two vectors of integers. 18381 18382 18383Arguments: 18384"""""""""" 18385 18386The 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. 18387 18388Semantics: 18389"""""""""" 18390 18391The '``llvm.vp.udiv``' intrinsic performs unsigned division 18392(:ref:`udiv <i_udiv>`) of the first and second vector operand on each enabled 18393lane. The result on disabled lanes is undefined. 18394 18395Examples: 18396""""""""" 18397 18398.. code-block:: llvm 18399 18400 %r = call <4 x i32> @llvm.vp.udiv.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18401 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18402 18403 %t = udiv <4 x i32> %a, %b 18404 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18405 18406 18407 18408.. _int_vp_srem: 18409 18410'``llvm.vp.srem.*``' Intrinsics 18411^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18412 18413Syntax: 18414""""""" 18415This is an overloaded intrinsic. 18416 18417:: 18418 18419 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>) 18420 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>) 18421 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>) 18422 18423Overview: 18424""""""""" 18425 18426Predicated computations of the signed remainder of two integer vectors. 18427 18428 18429Arguments: 18430"""""""""" 18431 18432The first two operands and the result have the same vector of integer type. The 18433third operand is the vector mask and has the same number of elements as the 18434result vector type. The fourth operand is the explicit vector length of the 18435operation. 18436 18437Semantics: 18438"""""""""" 18439 18440The '``llvm.vp.srem``' intrinsic computes the remainder of the signed division 18441(:ref:`srem <i_srem>`) of the first and second vector operand on each enabled 18442lane. The result on disabled lanes is undefined. 18443 18444Examples: 18445""""""""" 18446 18447.. code-block:: llvm 18448 18449 %r = call <4 x i32> @llvm.vp.srem.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18450 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18451 18452 %t = srem <4 x i32> %a, %b 18453 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18454 18455 18456 18457.. _int_vp_urem: 18458 18459'``llvm.vp.urem.*``' Intrinsics 18460^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18461 18462Syntax: 18463""""""" 18464This is an overloaded intrinsic. 18465 18466:: 18467 18468 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>) 18469 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>) 18470 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>) 18471 18472Overview: 18473""""""""" 18474 18475Predicated computation of the unsigned remainder of two integer vectors. 18476 18477 18478Arguments: 18479"""""""""" 18480 18481The first two operands and the result have the same vector of integer type. The 18482third operand is the vector mask and has the same number of elements as the 18483result vector type. The fourth operand is the explicit vector length of the 18484operation. 18485 18486Semantics: 18487"""""""""" 18488 18489The '``llvm.vp.urem``' intrinsic computes the remainder of the unsigned division 18490(:ref:`urem <i_urem>`) of the first and second vector operand on each enabled 18491lane. The result on disabled lanes is undefined. 18492 18493Examples: 18494""""""""" 18495 18496.. code-block:: llvm 18497 18498 %r = call <4 x i32> @llvm.vp.urem.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18499 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18500 18501 %t = urem <4 x i32> %a, %b 18502 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18503 18504 18505.. _int_vp_ashr: 18506 18507'``llvm.vp.ashr.*``' Intrinsics 18508^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18509 18510Syntax: 18511""""""" 18512This is an overloaded intrinsic. 18513 18514:: 18515 18516 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>) 18517 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>) 18518 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>) 18519 18520Overview: 18521""""""""" 18522 18523Vector-predicated arithmetic right-shift. 18524 18525 18526Arguments: 18527"""""""""" 18528 18529The first two operands and the result have the same vector of integer type. The 18530third operand is the vector mask and has the same number of elements as the 18531result vector type. The fourth operand is the explicit vector length of the 18532operation. 18533 18534Semantics: 18535"""""""""" 18536 18537The '``llvm.vp.ashr``' intrinsic computes the arithmetic right shift 18538(:ref:`ashr <i_ashr>`) of the first operand by the second operand on each 18539enabled lane. The result on disabled lanes is undefined. 18540 18541Examples: 18542""""""""" 18543 18544.. code-block:: llvm 18545 18546 %r = call <4 x i32> @llvm.vp.ashr.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18547 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18548 18549 %t = ashr <4 x i32> %a, %b 18550 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18551 18552 18553.. _int_vp_lshr: 18554 18555 18556'``llvm.vp.lshr.*``' Intrinsics 18557^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18558 18559Syntax: 18560""""""" 18561This is an overloaded intrinsic. 18562 18563:: 18564 18565 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>) 18566 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>) 18567 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>) 18568 18569Overview: 18570""""""""" 18571 18572Vector-predicated logical right-shift. 18573 18574 18575Arguments: 18576"""""""""" 18577 18578The first two operands and the result have the same vector of integer type. The 18579third operand is the vector mask and has the same number of elements as the 18580result vector type. The fourth operand is the explicit vector length of the 18581operation. 18582 18583Semantics: 18584"""""""""" 18585 18586The '``llvm.vp.lshr``' intrinsic computes the logical right shift 18587(:ref:`lshr <i_lshr>`) of the first operand by the second operand on each 18588enabled lane. The result on disabled lanes is undefined. 18589 18590Examples: 18591""""""""" 18592 18593.. code-block:: llvm 18594 18595 %r = call <4 x i32> @llvm.vp.lshr.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18596 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18597 18598 %t = lshr <4 x i32> %a, %b 18599 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18600 18601 18602.. _int_vp_shl: 18603 18604'``llvm.vp.shl.*``' Intrinsics 18605^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18606 18607Syntax: 18608""""""" 18609This is an overloaded intrinsic. 18610 18611:: 18612 18613 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>) 18614 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>) 18615 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>) 18616 18617Overview: 18618""""""""" 18619 18620Vector-predicated left shift. 18621 18622 18623Arguments: 18624"""""""""" 18625 18626The first two operands and the result have the same vector of integer type. The 18627third operand is the vector mask and has the same number of elements as the 18628result vector type. The fourth operand is the explicit vector length of the 18629operation. 18630 18631Semantics: 18632"""""""""" 18633 18634The '``llvm.vp.shl``' intrinsic computes the left shift (:ref:`shl <i_shl>`) of 18635the first operand by the second operand on each enabled lane. The result on 18636disabled lanes is undefined. 18637 18638Examples: 18639""""""""" 18640 18641.. code-block:: llvm 18642 18643 %r = call <4 x i32> @llvm.vp.shl.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18644 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18645 18646 %t = shl <4 x i32> %a, %b 18647 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18648 18649 18650.. _int_vp_or: 18651 18652'``llvm.vp.or.*``' Intrinsics 18653^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18654 18655Syntax: 18656""""""" 18657This is an overloaded intrinsic. 18658 18659:: 18660 18661 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>) 18662 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>) 18663 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>) 18664 18665Overview: 18666""""""""" 18667 18668Vector-predicated or. 18669 18670 18671Arguments: 18672"""""""""" 18673 18674The first two operands and the result have the same vector of integer type. The 18675third operand is the vector mask and has the same number of elements as the 18676result vector type. The fourth operand is the explicit vector length of the 18677operation. 18678 18679Semantics: 18680"""""""""" 18681 18682The '``llvm.vp.or``' intrinsic performs a bitwise or (:ref:`or <i_or>`) of the 18683first two operands on each enabled lane. The result on disabled lanes is 18684undefined. 18685 18686Examples: 18687""""""""" 18688 18689.. code-block:: llvm 18690 18691 %r = call <4 x i32> @llvm.vp.or.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18692 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18693 18694 %t = or <4 x i32> %a, %b 18695 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18696 18697 18698.. _int_vp_and: 18699 18700'``llvm.vp.and.*``' Intrinsics 18701^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18702 18703Syntax: 18704""""""" 18705This is an overloaded intrinsic. 18706 18707:: 18708 18709 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>) 18710 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>) 18711 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>) 18712 18713Overview: 18714""""""""" 18715 18716Vector-predicated and. 18717 18718 18719Arguments: 18720"""""""""" 18721 18722The first two operands and the result have the same vector of integer type. The 18723third operand is the vector mask and has the same number of elements as the 18724result vector type. The fourth operand is the explicit vector length of the 18725operation. 18726 18727Semantics: 18728"""""""""" 18729 18730The '``llvm.vp.and``' intrinsic performs a bitwise and (:ref:`and <i_or>`) of 18731the first two operands on each enabled lane. The result on disabled lanes is 18732undefined. 18733 18734Examples: 18735""""""""" 18736 18737.. code-block:: llvm 18738 18739 %r = call <4 x i32> @llvm.vp.and.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18740 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18741 18742 %t = and <4 x i32> %a, %b 18743 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18744 18745 18746.. _int_vp_xor: 18747 18748'``llvm.vp.xor.*``' Intrinsics 18749^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18750 18751Syntax: 18752""""""" 18753This is an overloaded intrinsic. 18754 18755:: 18756 18757 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>) 18758 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>) 18759 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>) 18760 18761Overview: 18762""""""""" 18763 18764Vector-predicated, bitwise xor. 18765 18766 18767Arguments: 18768"""""""""" 18769 18770The first two operands and the result have the same vector of integer type. The 18771third operand is the vector mask and has the same number of elements as the 18772result vector type. The fourth operand is the explicit vector length of the 18773operation. 18774 18775Semantics: 18776"""""""""" 18777 18778The '``llvm.vp.xor``' intrinsic performs a bitwise xor (:ref:`xor <i_xor>`) of 18779the first two operands on each enabled lane. 18780The result on disabled lanes is undefined. 18781 18782Examples: 18783""""""""" 18784 18785.. code-block:: llvm 18786 18787 %r = call <4 x i32> @llvm.vp.xor.v4i32(<4 x i32> %a, <4 x i32> %b, <4 x i1> %mask, i32 %evl) 18788 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18789 18790 %t = xor <4 x i32> %a, %b 18791 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 18792 18793 18794.. _int_vp_fadd: 18795 18796'``llvm.vp.fadd.*``' Intrinsics 18797^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18798 18799Syntax: 18800""""""" 18801This is an overloaded intrinsic. 18802 18803:: 18804 18805 declare <16 x float> @llvm.vp.fadd.v16f32 (<16 x float> <left_op>, <16 x float> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 18806 declare <vscale x 4 x float> @llvm.vp.fadd.nxv4f32 (<vscale x 4 x float> <left_op>, <vscale x 4 x float> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 18807 declare <256 x double> @llvm.vp.fadd.v256f64 (<256 x double> <left_op>, <256 x double> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 18808 18809Overview: 18810""""""""" 18811 18812Predicated floating-point addition of two vectors of floating-point values. 18813 18814 18815Arguments: 18816"""""""""" 18817 18818The first two operands and the result have the same vector of floating-point type. The 18819third operand is the vector mask and has the same number of elements as the 18820result vector type. The fourth operand is the explicit vector length of the 18821operation. 18822 18823Semantics: 18824"""""""""" 18825 18826The '``llvm.vp.fadd``' intrinsic performs floating-point addition (:ref:`fadd <i_fadd>`) 18827of the first and second vector operand on each enabled lane. The result on 18828disabled lanes is undefined. The operation is performed in the default 18829floating-point environment. 18830 18831Examples: 18832""""""""" 18833 18834.. code-block:: llvm 18835 18836 %r = call <4 x float> @llvm.vp.fadd.v4f32(<4 x float> %a, <4 x float> %b, <4 x i1> %mask, i32 %evl) 18837 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18838 18839 %t = fadd <4 x float> %a, %b 18840 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 18841 18842 18843.. _int_vp_fsub: 18844 18845'``llvm.vp.fsub.*``' Intrinsics 18846^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18847 18848Syntax: 18849""""""" 18850This is an overloaded intrinsic. 18851 18852:: 18853 18854 declare <16 x float> @llvm.vp.fsub.v16f32 (<16 x float> <left_op>, <16 x float> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 18855 declare <vscale x 4 x float> @llvm.vp.fsub.nxv4f32 (<vscale x 4 x float> <left_op>, <vscale x 4 x float> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 18856 declare <256 x double> @llvm.vp.fsub.v256f64 (<256 x double> <left_op>, <256 x double> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 18857 18858Overview: 18859""""""""" 18860 18861Predicated floating-point subtraction of two vectors of floating-point values. 18862 18863 18864Arguments: 18865"""""""""" 18866 18867The first two operands and the result have the same vector of floating-point type. The 18868third operand is the vector mask and has the same number of elements as the 18869result vector type. The fourth operand is the explicit vector length of the 18870operation. 18871 18872Semantics: 18873"""""""""" 18874 18875The '``llvm.vp.fsub``' intrinsic performs floating-point subtraction (:ref:`fsub <i_fsub>`) 18876of the first and second vector operand on each enabled lane. The result on 18877disabled lanes is undefined. The operation is performed in the default 18878floating-point environment. 18879 18880Examples: 18881""""""""" 18882 18883.. code-block:: llvm 18884 18885 %r = call <4 x float> @llvm.vp.fsub.v4f32(<4 x float> %a, <4 x float> %b, <4 x i1> %mask, i32 %evl) 18886 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18887 18888 %t = fsub <4 x float> %a, %b 18889 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 18890 18891 18892.. _int_vp_fmul: 18893 18894'``llvm.vp.fmul.*``' Intrinsics 18895^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18896 18897Syntax: 18898""""""" 18899This is an overloaded intrinsic. 18900 18901:: 18902 18903 declare <16 x float> @llvm.vp.fmul.v16f32 (<16 x float> <left_op>, <16 x float> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 18904 declare <vscale x 4 x float> @llvm.vp.fmul.nxv4f32 (<vscale x 4 x float> <left_op>, <vscale x 4 x float> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 18905 declare <256 x double> @llvm.vp.fmul.v256f64 (<256 x double> <left_op>, <256 x double> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 18906 18907Overview: 18908""""""""" 18909 18910Predicated floating-point multiplication of two vectors of floating-point values. 18911 18912 18913Arguments: 18914"""""""""" 18915 18916The first two operands and the result have the same vector of floating-point type. The 18917third operand is the vector mask and has the same number of elements as the 18918result vector type. The fourth operand is the explicit vector length of the 18919operation. 18920 18921Semantics: 18922"""""""""" 18923 18924The '``llvm.vp.fmul``' intrinsic performs floating-point multiplication (:ref:`fmul <i_fmul>`) 18925of the first and second vector operand on each enabled lane. The result on 18926disabled lanes is undefined. The operation is performed in the default 18927floating-point environment. 18928 18929Examples: 18930""""""""" 18931 18932.. code-block:: llvm 18933 18934 %r = call <4 x float> @llvm.vp.fmul.v4f32(<4 x float> %a, <4 x float> %b, <4 x i1> %mask, i32 %evl) 18935 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18936 18937 %t = fmul <4 x float> %a, %b 18938 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 18939 18940 18941.. _int_vp_fdiv: 18942 18943'``llvm.vp.fdiv.*``' Intrinsics 18944^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18945 18946Syntax: 18947""""""" 18948This is an overloaded intrinsic. 18949 18950:: 18951 18952 declare <16 x float> @llvm.vp.fdiv.v16f32 (<16 x float> <left_op>, <16 x float> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 18953 declare <vscale x 4 x float> @llvm.vp.fdiv.nxv4f32 (<vscale x 4 x float> <left_op>, <vscale x 4 x float> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 18954 declare <256 x double> @llvm.vp.fdiv.v256f64 (<256 x double> <left_op>, <256 x double> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 18955 18956Overview: 18957""""""""" 18958 18959Predicated floating-point division of two vectors of floating-point values. 18960 18961 18962Arguments: 18963"""""""""" 18964 18965The first two operands and the result have the same vector of floating-point type. The 18966third operand is the vector mask and has the same number of elements as the 18967result vector type. The fourth operand is the explicit vector length of the 18968operation. 18969 18970Semantics: 18971"""""""""" 18972 18973The '``llvm.vp.fdiv``' intrinsic performs floating-point division (:ref:`fdiv <i_fdiv>`) 18974of the first and second vector operand on each enabled lane. The result on 18975disabled lanes is undefined. The operation is performed in the default 18976floating-point environment. 18977 18978Examples: 18979""""""""" 18980 18981.. code-block:: llvm 18982 18983 %r = call <4 x float> @llvm.vp.fdiv.v4f32(<4 x float> %a, <4 x float> %b, <4 x i1> %mask, i32 %evl) 18984 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 18985 18986 %t = fdiv <4 x float> %a, %b 18987 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 18988 18989 18990.. _int_vp_frem: 18991 18992'``llvm.vp.frem.*``' Intrinsics 18993^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18994 18995Syntax: 18996""""""" 18997This is an overloaded intrinsic. 18998 18999:: 19000 19001 declare <16 x float> @llvm.vp.frem.v16f32 (<16 x float> <left_op>, <16 x float> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 19002 declare <vscale x 4 x float> @llvm.vp.frem.nxv4f32 (<vscale x 4 x float> <left_op>, <vscale x 4 x float> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 19003 declare <256 x double> @llvm.vp.frem.v256f64 (<256 x double> <left_op>, <256 x double> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 19004 19005Overview: 19006""""""""" 19007 19008Predicated floating-point remainder of two vectors of floating-point values. 19009 19010 19011Arguments: 19012"""""""""" 19013 19014The first two operands and the result have the same vector of floating-point type. The 19015third operand is the vector mask and has the same number of elements as the 19016result vector type. The fourth operand is the explicit vector length of the 19017operation. 19018 19019Semantics: 19020"""""""""" 19021 19022The '``llvm.vp.frem``' intrinsic performs floating-point remainder (:ref:`frem <i_frem>`) 19023of the first and second vector operand on each enabled lane. The result on 19024disabled lanes is undefined. The operation is performed in the default 19025floating-point environment. 19026 19027Examples: 19028""""""""" 19029 19030.. code-block:: llvm 19031 19032 %r = call <4 x float> @llvm.vp.frem.v4f32(<4 x float> %a, <4 x float> %b, <4 x i1> %mask, i32 %evl) 19033 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 19034 19035 %t = frem <4 x float> %a, %b 19036 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 19037 19038 19039.. _int_vp_fneg: 19040 19041'``llvm.vp.fneg.*``' Intrinsics 19042^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19043 19044Syntax: 19045""""""" 19046This is an overloaded intrinsic. 19047 19048:: 19049 19050 declare <16 x float> @llvm.vp.fneg.v16f32 (<16 x float> <op>, <16 x i1> <mask>, i32 <vector_length>) 19051 declare <vscale x 4 x float> @llvm.vp.fneg.nxv4f32 (<vscale x 4 x float> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 19052 declare <256 x double> @llvm.vp.fneg.v256f64 (<256 x double> <op>, <256 x i1> <mask>, i32 <vector_length>) 19053 19054Overview: 19055""""""""" 19056 19057Predicated floating-point negation of a vector of floating-point values. 19058 19059 19060Arguments: 19061"""""""""" 19062 19063The first operand and the result have the same vector of floating-point type. 19064The second operand is the vector mask and has the same number of elements as the 19065result vector type. The third operand is the explicit vector length of the 19066operation. 19067 19068Semantics: 19069"""""""""" 19070 19071The '``llvm.vp.fneg``' intrinsic performs floating-point negation (:ref:`fneg <i_fneg>`) 19072of the first vector operand on each enabled lane. The result on disabled lanes 19073is undefined. 19074 19075Examples: 19076""""""""" 19077 19078.. code-block:: llvm 19079 19080 %r = call <4 x float> @llvm.vp.fneg.v4f32(<4 x float> %a, <4 x i1> %mask, i32 %evl) 19081 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 19082 19083 %t = fneg <4 x float> %a 19084 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 19085 19086 19087.. _int_vp_fma: 19088 19089'``llvm.vp.fma.*``' Intrinsics 19090^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19091 19092Syntax: 19093""""""" 19094This is an overloaded intrinsic. 19095 19096:: 19097 19098 declare <16 x float> @llvm.vp.fma.v16f32 (<16 x float> <left_op>, <16 x float> <middle_op>, <16 x float> <right_op>, <16 x i1> <mask>, i32 <vector_length>) 19099 declare <vscale x 4 x float> @llvm.vp.fma.nxv4f32 (<vscale x 4 x float> <left_op>, <vscale x 4 x float> <middle_op>, <vscale x 4 x float> <right_op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 19100 declare <256 x double> @llvm.vp.fma.v256f64 (<256 x double> <left_op>, <256 x double> <middle_op>, <256 x double> <right_op>, <256 x i1> <mask>, i32 <vector_length>) 19101 19102Overview: 19103""""""""" 19104 19105Predicated floating-point fused multiply-add of two vectors of floating-point values. 19106 19107 19108Arguments: 19109"""""""""" 19110 19111The first three operands and the result have the same vector of floating-point type. The 19112fourth operand is the vector mask and has the same number of elements as the 19113result vector type. The fifth operand is the explicit vector length of the 19114operation. 19115 19116Semantics: 19117"""""""""" 19118 19119The '``llvm.vp.fma``' intrinsic performs floating-point fused multiply-add (:ref:`llvm.fma <int_fma>`) 19120of the first, second, and third vector operand on each enabled lane. The result on 19121disabled lanes is undefined. The operation is performed in the default 19122floating-point environment. 19123 19124Examples: 19125""""""""" 19126 19127.. code-block:: llvm 19128 19129 %r = call <4 x float> @llvm.vp.fma.v4f32(<4 x float> %a, <4 x float> %b, <4 x float> %c, <4 x i1> %mask, i32 %evl) 19130 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 19131 19132 %t = call <4 x float> @llvm.fma(<4 x float> %a, <4 x float> %b, <4 x float> %c) 19133 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 19134 19135 19136.. _int_vp_reduce_add: 19137 19138'``llvm.vp.reduce.add.*``' Intrinsics 19139^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19140 19141Syntax: 19142""""""" 19143This is an overloaded intrinsic. 19144 19145:: 19146 19147 declare i32 @llvm.vp.reduce.add.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19148 declare i16 @llvm.vp.reduce.add.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19149 19150Overview: 19151""""""""" 19152 19153Predicated integer ``ADD`` reduction of a vector and a scalar starting value, 19154returning the result as a scalar. 19155 19156Arguments: 19157"""""""""" 19158 19159The first operand is the start value of the reduction, which must be a scalar 19160integer type equal to the result type. The second operand is the vector on 19161which the reduction is performed and must be a vector of integer values whose 19162element type is the result/start type. The third operand is the vector mask and 19163is a vector of boolean values with the same number of elements as the vector 19164operand. The fourth operand is the explicit vector length of the operation. 19165 19166Semantics: 19167"""""""""" 19168 19169The '``llvm.vp.reduce.add``' intrinsic performs the integer ``ADD`` reduction 19170(:ref:`llvm.vector.reduce.add <int_vector_reduce_add>`) of the vector operand 19171``val`` on each enabled lane, adding it to the scalar ``start_value``. Disabled 19172lanes are treated as containing the neutral value ``0`` (i.e. having no effect 19173on the reduction operation). If the vector length is zero, the result is equal 19174to ``start_value``. 19175 19176To ignore the start value, the neutral value can be used. 19177 19178Examples: 19179""""""""" 19180 19181.. code-block:: llvm 19182 19183 %r = call i32 @llvm.vp.reduce.add.v4i32(i32 %start, <4 x i32> %a, <4 x i1> %mask, i32 %evl) 19184 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19185 ; are treated as though %mask were false for those lanes. 19186 19187 %masked.a = select <4 x i1> %mask, <4 x i32> %a, <4 x i32> zeroinitializer 19188 %reduction = call i32 @llvm.vector.reduce.add.v4i32(<4 x i32> %masked.a) 19189 %also.r = add i32 %reduction, %start 19190 19191 19192.. _int_vp_reduce_fadd: 19193 19194'``llvm.vp.reduce.fadd.*``' Intrinsics 19195^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19196 19197Syntax: 19198""""""" 19199This is an overloaded intrinsic. 19200 19201:: 19202 19203 declare float @llvm.vp.reduce.fadd.v4f32(float <start_value>, <4 x float> <val>, <4 x i1> <mask>, i32 <vector_length>) 19204 declare double @llvm.vp.reduce.fadd.nxv8f64(double <start_value>, <vscale x 8 x double> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19205 19206Overview: 19207""""""""" 19208 19209Predicated floating-point ``ADD`` reduction of a vector and a scalar starting 19210value, returning the result as a scalar. 19211 19212Arguments: 19213"""""""""" 19214 19215The first operand is the start value of the reduction, which must be a scalar 19216floating-point type equal to the result type. The second operand is the vector 19217on which the reduction is performed and must be a vector of floating-point 19218values whose element type is the result/start type. The third operand is the 19219vector mask and is a vector of boolean values with the same number of elements 19220as the vector operand. The fourth operand is the explicit vector length of the 19221operation. 19222 19223Semantics: 19224"""""""""" 19225 19226The '``llvm.vp.reduce.fadd``' intrinsic performs the floating-point ``ADD`` 19227reduction (:ref:`llvm.vector.reduce.fadd <int_vector_reduce_fadd>`) of the 19228vector operand ``val`` on each enabled lane, adding it to the scalar 19229``start_value``. Disabled lanes are treated as containing the neutral value 19230``-0.0`` (i.e. having no effect on the reduction operation). If no lanes are 19231enabled, the resulting value will be equal to ``start_value``. 19232 19233To ignore the start value, the neutral value can be used. 19234 19235See the unpredicated version (:ref:`llvm.vector.reduce.fadd 19236<int_vector_reduce_fadd>`) for more detail on the semantics of the reduction. 19237 19238Examples: 19239""""""""" 19240 19241.. code-block:: llvm 19242 19243 %r = call float @llvm.vp.reduce.fadd.v4f32(float %start, <4 x float> %a, <4 x i1> %mask, i32 %evl) 19244 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19245 ; are treated as though %mask were false for those lanes. 19246 19247 %masked.a = select <4 x i1> %mask, <4 x float> %a, <4 x float> <float -0.0, float -0.0, float -0.0, float -0.0> 19248 %also.r = call float @llvm.vector.reduce.fadd.v4f32(float %start, <4 x float> %masked.a) 19249 19250 19251.. _int_vp_reduce_mul: 19252 19253'``llvm.vp.reduce.mul.*``' Intrinsics 19254^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19255 19256Syntax: 19257""""""" 19258This is an overloaded intrinsic. 19259 19260:: 19261 19262 declare i32 @llvm.vp.reduce.mul.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19263 declare i16 @llvm.vp.reduce.mul.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19264 19265Overview: 19266""""""""" 19267 19268Predicated integer ``MUL`` reduction of a vector and a scalar starting value, 19269returning the result as a scalar. 19270 19271 19272Arguments: 19273"""""""""" 19274 19275The first operand is the start value of the reduction, which must be a scalar 19276integer type equal to the result type. The second operand is the vector on 19277which the reduction is performed and must be a vector of integer values whose 19278element type is the result/start type. The third operand is the vector mask and 19279is a vector of boolean values with the same number of elements as the vector 19280operand. The fourth operand is the explicit vector length of the operation. 19281 19282Semantics: 19283"""""""""" 19284 19285The '``llvm.vp.reduce.mul``' intrinsic performs the integer ``MUL`` reduction 19286(:ref:`llvm.vector.reduce.mul <int_vector_reduce_mul>`) of the vector operand ``val`` 19287on each enabled lane, multiplying it by the scalar ``start_value``. Disabled 19288lanes are treated as containing the neutral value ``1`` (i.e. having no effect 19289on the reduction operation). If the vector length is zero, the result is the 19290start value. 19291 19292To ignore the start value, the neutral value can be used. 19293 19294Examples: 19295""""""""" 19296 19297.. code-block:: llvm 19298 19299 %r = call i32 @llvm.vp.reduce.mul.v4i32(i32 %start, <4 x i32> %a, <4 x i1> %mask, i32 %evl) 19300 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19301 ; are treated as though %mask were false for those lanes. 19302 19303 %masked.a = select <4 x i1> %mask, <4 x i32> %a, <4 x i32> <i32 1, i32 1, i32 1, i32 1> 19304 %reduction = call i32 @llvm.vector.reduce.mul.v4i32(<4 x i32> %masked.a) 19305 %also.r = mul i32 %reduction, %start 19306 19307.. _int_vp_reduce_fmul: 19308 19309'``llvm.vp.reduce.fmul.*``' Intrinsics 19310^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19311 19312Syntax: 19313""""""" 19314This is an overloaded intrinsic. 19315 19316:: 19317 19318 declare float @llvm.vp.reduce.fmul.v4f32(float <start_value>, <4 x float> <val>, <4 x i1> <mask>, i32 <vector_length>) 19319 declare double @llvm.vp.reduce.fmul.nxv8f64(double <start_value>, <vscale x 8 x double> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19320 19321Overview: 19322""""""""" 19323 19324Predicated floating-point ``MUL`` reduction of a vector and a scalar starting 19325value, returning the result as a scalar. 19326 19327 19328Arguments: 19329"""""""""" 19330 19331The first operand is the start value of the reduction, which must be a scalar 19332floating-point type equal to the result type. The second operand is the vector 19333on which the reduction is performed and must be a vector of floating-point 19334values whose element type is the result/start type. The third operand is the 19335vector mask and is a vector of boolean values with the same number of elements 19336as the vector operand. The fourth operand is the explicit vector length of the 19337operation. 19338 19339Semantics: 19340"""""""""" 19341 19342The '``llvm.vp.reduce.fmul``' intrinsic performs the floating-point ``MUL`` 19343reduction (:ref:`llvm.vector.reduce.fmul <int_vector_reduce_fmul>`) of the 19344vector operand ``val`` on each enabled lane, multiplying it by the scalar 19345`start_value``. Disabled lanes are treated as containing the neutral value 19346``1.0`` (i.e. having no effect on the reduction operation). If no lanes are 19347enabled, the resulting value will be equal to the starting value. 19348 19349To ignore the start value, the neutral value can be used. 19350 19351See the unpredicated version (:ref:`llvm.vector.reduce.fmul 19352<int_vector_reduce_fmul>`) for more detail on the semantics. 19353 19354Examples: 19355""""""""" 19356 19357.. code-block:: llvm 19358 19359 %r = call float @llvm.vp.reduce.fmul.v4f32(float %start, <4 x float> %a, <4 x i1> %mask, i32 %evl) 19360 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19361 ; are treated as though %mask were false for those lanes. 19362 19363 %masked.a = select <4 x i1> %mask, <4 x float> %a, <4 x float> <float 1.0, float 1.0, float 1.0, float 1.0> 19364 %also.r = call float @llvm.vector.reduce.fmul.v4f32(float %start, <4 x float> %masked.a) 19365 19366 19367.. _int_vp_reduce_and: 19368 19369'``llvm.vp.reduce.and.*``' Intrinsics 19370^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19371 19372Syntax: 19373""""""" 19374This is an overloaded intrinsic. 19375 19376:: 19377 19378 declare i32 @llvm.vp.reduce.and.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19379 declare i16 @llvm.vp.reduce.and.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19380 19381Overview: 19382""""""""" 19383 19384Predicated integer ``AND`` reduction of a vector and a scalar starting value, 19385returning the result as a scalar. 19386 19387 19388Arguments: 19389"""""""""" 19390 19391The first operand is the start value of the reduction, which must be a scalar 19392integer type equal to the result type. The second operand is the vector on 19393which the reduction is performed and must be a vector of integer values whose 19394element type is the result/start type. The third operand is the vector mask and 19395is a vector of boolean values with the same number of elements as the vector 19396operand. The fourth operand is the explicit vector length of the operation. 19397 19398Semantics: 19399"""""""""" 19400 19401The '``llvm.vp.reduce.and``' intrinsic performs the integer ``AND`` reduction 19402(:ref:`llvm.vector.reduce.and <int_vector_reduce_and>`) of the vector operand 19403``val`` on each enabled lane, performing an '``and``' of that with with the 19404scalar ``start_value``. Disabled lanes are treated as containing the neutral 19405value ``UINT_MAX``, or ``-1`` (i.e. having no effect on the reduction 19406operation). If the vector length is zero, the result is the start value. 19407 19408To ignore the start value, the neutral value can be used. 19409 19410Examples: 19411""""""""" 19412 19413.. code-block:: llvm 19414 19415 %r = call i32 @llvm.vp.reduce.and.v4i32(i32 %start, <4 x i32> %a, <4 x i1> %mask, i32 %evl) 19416 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19417 ; are treated as though %mask were false for those lanes. 19418 19419 %masked.a = select <4 x i1> %mask, <4 x i32> %a, <4 x i32> <i32 -1, i32 -1, i32 -1, i32 -1> 19420 %reduction = call i32 @llvm.vector.reduce.and.v4i32(<4 x i32> %masked.a) 19421 %also.r = and i32 %reduction, %start 19422 19423 19424.. _int_vp_reduce_or: 19425 19426'``llvm.vp.reduce.or.*``' Intrinsics 19427^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19428 19429Syntax: 19430""""""" 19431This is an overloaded intrinsic. 19432 19433:: 19434 19435 declare i32 @llvm.vp.reduce.or.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19436 declare i16 @llvm.vp.reduce.or.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19437 19438Overview: 19439""""""""" 19440 19441Predicated integer ``OR`` reduction of a vector and a scalar starting value, 19442returning the result as a scalar. 19443 19444 19445Arguments: 19446"""""""""" 19447 19448The first operand is the start value of the reduction, which must be a scalar 19449integer type equal to the result type. The second operand is the vector on 19450which the reduction is performed and must be a vector of integer values whose 19451element type is the result/start type. The third operand is the vector mask and 19452is a vector of boolean values with the same number of elements as the vector 19453operand. The fourth operand is the explicit vector length of the operation. 19454 19455Semantics: 19456"""""""""" 19457 19458The '``llvm.vp.reduce.or``' intrinsic performs the integer ``OR`` reduction 19459(:ref:`llvm.vector.reduce.or <int_vector_reduce_or>`) of the vector operand 19460``val`` on each enabled lane, performing an '``or``' of that with the scalar 19461``start_value``. Disabled lanes are treated as containing the neutral value 19462``0`` (i.e. having no effect on the reduction operation). If the vector length 19463is zero, the result is the start value. 19464 19465To ignore the start value, the neutral value can be used. 19466 19467Examples: 19468""""""""" 19469 19470.. code-block:: llvm 19471 19472 %r = call i32 @llvm.vp.reduce.or.v4i32(i32 %start, <4 x i32> %a, <4 x i1> %mask, i32 %evl) 19473 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19474 ; are treated as though %mask were false for those lanes. 19475 19476 %masked.a = select <4 x i1> %mask, <4 x i32> %a, <4 x i32> <i32 0, i32 0, i32 0, i32 0> 19477 %reduction = call i32 @llvm.vector.reduce.or.v4i32(<4 x i32> %masked.a) 19478 %also.r = or i32 %reduction, %start 19479 19480.. _int_vp_reduce_xor: 19481 19482'``llvm.vp.reduce.xor.*``' Intrinsics 19483^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19484 19485Syntax: 19486""""""" 19487This is an overloaded intrinsic. 19488 19489:: 19490 19491 declare i32 @llvm.vp.reduce.xor.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19492 declare i16 @llvm.vp.reduce.xor.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19493 19494Overview: 19495""""""""" 19496 19497Predicated integer ``XOR`` reduction of a vector and a scalar starting value, 19498returning the result as a scalar. 19499 19500 19501Arguments: 19502"""""""""" 19503 19504The first operand is the start value of the reduction, which must be a scalar 19505integer type equal to the result type. The second operand is the vector on 19506which the reduction is performed and must be a vector of integer values whose 19507element type is the result/start type. The third operand is the vector mask and 19508is a vector of boolean values with the same number of elements as the vector 19509operand. The fourth operand is the explicit vector length of the operation. 19510 19511Semantics: 19512"""""""""" 19513 19514The '``llvm.vp.reduce.xor``' intrinsic performs the integer ``XOR`` reduction 19515(:ref:`llvm.vector.reduce.xor <int_vector_reduce_xor>`) of the vector operand 19516``val`` on each enabled lane, performing an '``xor``' of that with the scalar 19517``start_value``. Disabled lanes are treated as containing the neutral value 19518``0`` (i.e. having no effect on the reduction operation). If the vector length 19519is zero, the result is the start value. 19520 19521To ignore the start value, the neutral value can be used. 19522 19523Examples: 19524""""""""" 19525 19526.. code-block:: llvm 19527 19528 %r = call i32 @llvm.vp.reduce.xor.v4i32(i32 %start, <4 x i32> %a, <4 x i1> %mask, i32 %evl) 19529 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19530 ; are treated as though %mask were false for those lanes. 19531 19532 %masked.a = select <4 x i1> %mask, <4 x i32> %a, <4 x i32> <i32 0, i32 0, i32 0, i32 0> 19533 %reduction = call i32 @llvm.vector.reduce.xor.v4i32(<4 x i32> %masked.a) 19534 %also.r = xor i32 %reduction, %start 19535 19536 19537.. _int_vp_reduce_smax: 19538 19539'``llvm.vp.reduce.smax.*``' Intrinsics 19540^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19541 19542Syntax: 19543""""""" 19544This is an overloaded intrinsic. 19545 19546:: 19547 19548 declare i32 @llvm.vp.reduce.smax.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19549 declare i16 @llvm.vp.reduce.smax.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19550 19551Overview: 19552""""""""" 19553 19554Predicated signed-integer ``MAX`` reduction of a vector and a scalar starting 19555value, returning the result as a scalar. 19556 19557 19558Arguments: 19559"""""""""" 19560 19561The first operand is the start value of the reduction, which must be a scalar 19562integer type equal to the result type. The second operand is the vector on 19563which the reduction is performed and must be a vector of integer values whose 19564element type is the result/start type. The third operand is the vector mask and 19565is a vector of boolean values with the same number of elements as the vector 19566operand. The fourth operand is the explicit vector length of the operation. 19567 19568Semantics: 19569"""""""""" 19570 19571The '``llvm.vp.reduce.smax``' intrinsic performs the signed-integer ``MAX`` 19572reduction (:ref:`llvm.vector.reduce.smax <int_vector_reduce_smax>`) of the 19573vector operand ``val`` on each enabled lane, and taking the maximum of that and 19574the scalar ``start_value``. Disabled lanes are treated as containing the 19575neutral value ``INT_MIN`` (i.e. having no effect on the reduction operation). 19576If the vector length is zero, the result is the start value. 19577 19578To ignore the start value, the neutral value can be used. 19579 19580Examples: 19581""""""""" 19582 19583.. code-block:: llvm 19584 19585 %r = call i8 @llvm.vp.reduce.smax.v4i8(i8 %start, <4 x i8> %a, <4 x i1> %mask, i32 %evl) 19586 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19587 ; are treated as though %mask were false for those lanes. 19588 19589 %masked.a = select <4 x i1> %mask, <4 x i8> %a, <4 x i8> <i8 -128, i8 -128, i8 -128, i8 -128> 19590 %reduction = call i8 @llvm.vector.reduce.smax.v4i8(<4 x i8> %masked.a) 19591 %also.r = call i8 @llvm.smax.i8(i8 %reduction, i8 %start) 19592 19593 19594.. _int_vp_reduce_smin: 19595 19596'``llvm.vp.reduce.smin.*``' Intrinsics 19597^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19598 19599Syntax: 19600""""""" 19601This is an overloaded intrinsic. 19602 19603:: 19604 19605 declare i32 @llvm.vp.reduce.smin.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19606 declare i16 @llvm.vp.reduce.smin.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19607 19608Overview: 19609""""""""" 19610 19611Predicated signed-integer ``MIN`` reduction of a vector and a scalar starting 19612value, returning the result as a scalar. 19613 19614 19615Arguments: 19616"""""""""" 19617 19618The first operand is the start value of the reduction, which must be a scalar 19619integer type equal to the result type. The second operand is the vector on 19620which the reduction is performed and must be a vector of integer values whose 19621element type is the result/start type. The third operand is the vector mask and 19622is a vector of boolean values with the same number of elements as the vector 19623operand. The fourth operand is the explicit vector length of the operation. 19624 19625Semantics: 19626"""""""""" 19627 19628The '``llvm.vp.reduce.smin``' intrinsic performs the signed-integer ``MIN`` 19629reduction (:ref:`llvm.vector.reduce.smin <int_vector_reduce_smin>`) of the 19630vector operand ``val`` on each enabled lane, and taking the minimum of that and 19631the scalar ``start_value``. Disabled lanes are treated as containing the 19632neutral value ``INT_MAX`` (i.e. having no effect on the reduction operation). 19633If the vector length is zero, the result is the start value. 19634 19635To ignore the start value, the neutral value can be used. 19636 19637Examples: 19638""""""""" 19639 19640.. code-block:: llvm 19641 19642 %r = call i8 @llvm.vp.reduce.smin.v4i8(i8 %start, <4 x i8> %a, <4 x i1> %mask, i32 %evl) 19643 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19644 ; are treated as though %mask were false for those lanes. 19645 19646 %masked.a = select <4 x i1> %mask, <4 x i8> %a, <4 x i8> <i8 127, i8 127, i8 127, i8 127> 19647 %reduction = call i8 @llvm.vector.reduce.smin.v4i8(<4 x i8> %masked.a) 19648 %also.r = call i8 @llvm.smin.i8(i8 %reduction, i8 %start) 19649 19650 19651.. _int_vp_reduce_umax: 19652 19653'``llvm.vp.reduce.umax.*``' Intrinsics 19654^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19655 19656Syntax: 19657""""""" 19658This is an overloaded intrinsic. 19659 19660:: 19661 19662 declare i32 @llvm.vp.reduce.umax.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19663 declare i16 @llvm.vp.reduce.umax.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19664 19665Overview: 19666""""""""" 19667 19668Predicated unsigned-integer ``MAX`` reduction of a vector and a scalar starting 19669value, returning the result as a scalar. 19670 19671 19672Arguments: 19673"""""""""" 19674 19675The first operand is the start value of the reduction, which must be a scalar 19676integer type equal to the result type. The second operand is the vector on 19677which the reduction is performed and must be a vector of integer values whose 19678element type is the result/start type. The third operand is the vector mask and 19679is a vector of boolean values with the same number of elements as the vector 19680operand. The fourth operand is the explicit vector length of the operation. 19681 19682Semantics: 19683"""""""""" 19684 19685The '``llvm.vp.reduce.umax``' intrinsic performs the unsigned-integer ``MAX`` 19686reduction (:ref:`llvm.vector.reduce.umax <int_vector_reduce_umax>`) of the 19687vector operand ``val`` on each enabled lane, and taking the maximum of that and 19688the scalar ``start_value``. Disabled lanes are treated as containing the 19689neutral value ``0`` (i.e. having no effect on the reduction operation). If the 19690vector length is zero, the result is the start value. 19691 19692To ignore the start value, the neutral value can be used. 19693 19694Examples: 19695""""""""" 19696 19697.. code-block:: llvm 19698 19699 %r = call i32 @llvm.vp.reduce.umax.v4i32(i32 %start, <4 x i32> %a, <4 x i1> %mask, i32 %evl) 19700 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19701 ; are treated as though %mask were false for those lanes. 19702 19703 %masked.a = select <4 x i1> %mask, <4 x i32> %a, <4 x i32> <i32 0, i32 0, i32 0, i32 0> 19704 %reduction = call i32 @llvm.vector.reduce.umax.v4i32(<4 x i32> %masked.a) 19705 %also.r = call i32 @llvm.umax.i32(i32 %reduction, i32 %start) 19706 19707 19708.. _int_vp_reduce_umin: 19709 19710'``llvm.vp.reduce.umin.*``' Intrinsics 19711^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19712 19713Syntax: 19714""""""" 19715This is an overloaded intrinsic. 19716 19717:: 19718 19719 declare i32 @llvm.vp.reduce.umin.v4i32(i32 <start_value>, <4 x i32> <val>, <4 x i1> <mask>, i32 <vector_length>) 19720 declare i16 @llvm.vp.reduce.umin.nxv8i16(i16 <start_value>, <vscale x 8 x i16> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19721 19722Overview: 19723""""""""" 19724 19725Predicated unsigned-integer ``MIN`` reduction of a vector and a scalar starting 19726value, returning the result as a scalar. 19727 19728 19729Arguments: 19730"""""""""" 19731 19732The first operand is the start value of the reduction, which must be a scalar 19733integer type equal to the result type. The second operand is the vector on 19734which the reduction is performed and must be a vector of integer values whose 19735element type is the result/start type. The third operand is the vector mask and 19736is a vector of boolean values with the same number of elements as the vector 19737operand. The fourth operand is the explicit vector length of the operation. 19738 19739Semantics: 19740"""""""""" 19741 19742The '``llvm.vp.reduce.umin``' intrinsic performs the unsigned-integer ``MIN`` 19743reduction (:ref:`llvm.vector.reduce.umin <int_vector_reduce_umin>`) of the 19744vector operand ``val`` on each enabled lane, taking the minimum of that and the 19745scalar ``start_value``. Disabled lanes are treated as containing the neutral 19746value ``UINT_MAX``, or ``-1`` (i.e. having no effect on the reduction 19747operation). If the vector length is zero, the result is the start value. 19748 19749To ignore the start value, the neutral value can be used. 19750 19751Examples: 19752""""""""" 19753 19754.. code-block:: llvm 19755 19756 %r = call i32 @llvm.vp.reduce.umin.v4i32(i32 %start, <4 x i32> %a, <4 x i1> %mask, i32 %evl) 19757 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19758 ; are treated as though %mask were false for those lanes. 19759 19760 %masked.a = select <4 x i1> %mask, <4 x i32> %a, <4 x i32> <i32 -1, i32 -1, i32 -1, i32 -1> 19761 %reduction = call i32 @llvm.vector.reduce.umin.v4i32(<4 x i32> %masked.a) 19762 %also.r = call i32 @llvm.umin.i32(i32 %reduction, i32 %start) 19763 19764 19765.. _int_vp_reduce_fmax: 19766 19767'``llvm.vp.reduce.fmax.*``' Intrinsics 19768^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19769 19770Syntax: 19771""""""" 19772This is an overloaded intrinsic. 19773 19774:: 19775 19776 declare float @llvm.vp.reduce.fmax.v4f32(float <start_value>, <4 x float> <val>, <4 x i1> <mask>, float <vector_length>) 19777 declare double @llvm.vp.reduce.fmax.nxv8f64(double <start_value>, <vscale x 8 x double> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19778 19779Overview: 19780""""""""" 19781 19782Predicated floating-point ``MAX`` reduction of a vector and a scalar starting 19783value, returning the result as a scalar. 19784 19785 19786Arguments: 19787"""""""""" 19788 19789The first operand is the start value of the reduction, which must be a scalar 19790floating-point type equal to the result type. The second operand is the vector 19791on which the reduction is performed and must be a vector of floating-point 19792values whose element type is the result/start type. The third operand is the 19793vector mask and is a vector of boolean values with the same number of elements 19794as the vector operand. The fourth operand is the explicit vector length of the 19795operation. 19796 19797Semantics: 19798"""""""""" 19799 19800The '``llvm.vp.reduce.fmax``' intrinsic performs the floating-point ``MAX`` 19801reduction (:ref:`llvm.vector.reduce.fmax <int_vector_reduce_fmax>`) of the 19802vector operand ``val`` on each enabled lane, taking the maximum of that and the 19803scalar ``start_value``. Disabled lanes are treated as containing the neutral 19804value (i.e. having no effect on the reduction operation). If the vector length 19805is zero, the result is the start value. 19806 19807The neutral value is dependent on the :ref:`fast-math flags <fastmath>`. If no 19808flags are set, the neutral value is ``-QNAN``. If ``nnan`` and ``ninf`` are 19809both set, then the neutral value is the smallest floating-point value for the 19810result type. If only ``nnan`` is set then the neutral value is ``-Infinity``. 19811 19812This instruction has the same comparison semantics as the 19813:ref:`llvm.vector.reduce.fmax <int_vector_reduce_fmax>` intrinsic (and thus the 19814'``llvm.maxnum.*``' intrinsic). That is, the result will always be a number 19815unless all elements of the vector and the starting value are ``NaN``. For a 19816vector with maximum element magnitude ``0.0`` and containing both ``+0.0`` and 19817``-0.0`` elements, the sign of the result is unspecified. 19818 19819To ignore the start value, the neutral value can be used. 19820 19821Examples: 19822""""""""" 19823 19824.. code-block:: llvm 19825 19826 %r = call float @llvm.vp.reduce.fmax.v4f32(float %float, <4 x float> %a, <4 x i1> %mask, i32 %evl) 19827 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19828 ; are treated as though %mask were false for those lanes. 19829 19830 %masked.a = select <4 x i1> %mask, <4 x float> %a, <4 x float> <float QNAN, float QNAN, float QNAN, float QNAN> 19831 %reduction = call float @llvm.vector.reduce.fmax.v4f32(<4 x float> %masked.a) 19832 %also.r = call float @llvm.maxnum.f32(float %reduction, float %start) 19833 19834 19835.. _int_vp_reduce_fmin: 19836 19837'``llvm.vp.reduce.fmin.*``' Intrinsics 19838^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19839 19840Syntax: 19841""""""" 19842This is an overloaded intrinsic. 19843 19844:: 19845 19846 declare float @llvm.vp.reduce.fmin.v4f32(float <start_value>, <4 x float> <val>, <4 x i1> <mask>, float <vector_length>) 19847 declare double @llvm.vp.reduce.fmin.nxv8f64(double <start_value>, <vscale x 8 x double> <val>, <vscale x 8 x i1> <mask>, i32 <vector_length>) 19848 19849Overview: 19850""""""""" 19851 19852Predicated floating-point ``MIN`` reduction of a vector and a scalar starting 19853value, returning the result as a scalar. 19854 19855 19856Arguments: 19857"""""""""" 19858 19859The first operand is the start value of the reduction, which must be a scalar 19860floating-point type equal to the result type. The second operand is the vector 19861on which the reduction is performed and must be a vector of floating-point 19862values whose element type is the result/start type. The third operand is the 19863vector mask and is a vector of boolean values with the same number of elements 19864as the vector operand. The fourth operand is the explicit vector length of the 19865operation. 19866 19867Semantics: 19868"""""""""" 19869 19870The '``llvm.vp.reduce.fmin``' intrinsic performs the floating-point ``MIN`` 19871reduction (:ref:`llvm.vector.reduce.fmin <int_vector_reduce_fmin>`) of the 19872vector operand ``val`` on each enabled lane, taking the minimum of that and the 19873scalar ``start_value``. Disabled lanes are treated as containing the neutral 19874value (i.e. having no effect on the reduction operation). If the vector length 19875is zero, the result is the start value. 19876 19877The neutral value is dependent on the :ref:`fast-math flags <fastmath>`. If no 19878flags are set, the neutral value is ``+QNAN``. If ``nnan`` and ``ninf`` are 19879both set, then the neutral value is the largest floating-point value for the 19880result type. If only ``nnan`` is set then the neutral value is ``+Infinity``. 19881 19882This instruction has the same comparison semantics as the 19883:ref:`llvm.vector.reduce.fmin <int_vector_reduce_fmin>` intrinsic (and thus the 19884'``llvm.minnum.*``' intrinsic). That is, the result will always be a number 19885unless all elements of the vector and the starting value are ``NaN``. For a 19886vector with maximum element magnitude ``0.0`` and containing both ``+0.0`` and 19887``-0.0`` elements, the sign of the result is unspecified. 19888 19889To ignore the start value, the neutral value can be used. 19890 19891Examples: 19892""""""""" 19893 19894.. code-block:: llvm 19895 19896 %r = call float @llvm.vp.reduce.fmin.v4f32(float %start, <4 x float> %a, <4 x i1> %mask, i32 %evl) 19897 ; %r is equivalent to %also.r, where lanes greater than or equal to %evl 19898 ; are treated as though %mask were false for those lanes. 19899 19900 %masked.a = select <4 x i1> %mask, <4 x float> %a, <4 x float> <float QNAN, float QNAN, float QNAN, float QNAN> 19901 %reduction = call float @llvm.vector.reduce.fmin.v4f32(<4 x float> %masked.a) 19902 %also.r = call float @llvm.minnum.f32(float %reduction, float %start) 19903 19904 19905.. _int_get_active_lane_mask: 19906 19907'``llvm.get.active.lane.mask.*``' Intrinsics 19908^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19909 19910Syntax: 19911""""""" 19912This is an overloaded intrinsic. 19913 19914:: 19915 19916 declare <4 x i1> @llvm.get.active.lane.mask.v4i1.i32(i32 %base, i32 %n) 19917 declare <8 x i1> @llvm.get.active.lane.mask.v8i1.i64(i64 %base, i64 %n) 19918 declare <16 x i1> @llvm.get.active.lane.mask.v16i1.i64(i64 %base, i64 %n) 19919 declare <vscale x 16 x i1> @llvm.get.active.lane.mask.nxv16i1.i64(i64 %base, i64 %n) 19920 19921 19922Overview: 19923""""""""" 19924 19925Create a mask representing active and inactive vector lanes. 19926 19927 19928Arguments: 19929"""""""""" 19930 19931Both operands have the same scalar integer type. The result is a vector with 19932the i1 element type. 19933 19934Semantics: 19935"""""""""" 19936 19937The '``llvm.get.active.lane.mask.*``' intrinsics are semantically equivalent 19938to: 19939 19940:: 19941 19942 %m[i] = icmp ult (%base + i), %n 19943 19944where ``%m`` is a vector (mask) of active/inactive lanes with its elements 19945indexed by ``i``, and ``%base``, ``%n`` are the two arguments to 19946``llvm.get.active.lane.mask.*``, ``%icmp`` is an integer compare and ``ult`` 19947the unsigned less-than comparison operator. Overflow cannot occur in 19948``(%base + i)`` and its comparison against ``%n`` as it is performed in integer 19949numbers and not in machine numbers. If ``%n`` is ``0``, then the result is a 19950poison value. The above is equivalent to: 19951 19952:: 19953 19954 %m = @llvm.get.active.lane.mask(%base, %n) 19955 19956This can, for example, be emitted by the loop vectorizer in which case 19957``%base`` is the first element of the vector induction variable (VIV) and 19958``%n`` is the loop tripcount. Thus, these intrinsics perform an element-wise 19959less than comparison of VIV with the loop tripcount, producing a mask of 19960true/false values representing active/inactive vector lanes, except if the VIV 19961overflows in which case they return false in the lanes where the VIV overflows. 19962The arguments are scalar types to accommodate scalable vector types, for which 19963it is unknown what the type of the step vector needs to be that enumerate its 19964lanes without overflow. 19965 19966This mask ``%m`` can e.g. be used in masked load/store instructions. These 19967intrinsics provide a hint to the backend. I.e., for a vector loop, the 19968back-edge taken count of the original scalar loop is explicit as the second 19969argument. 19970 19971 19972Examples: 19973""""""""" 19974 19975.. code-block:: llvm 19976 19977 %active.lane.mask = call <4 x i1> @llvm.get.active.lane.mask.v4i1.i64(i64 %elem0, i64 429) 19978 %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) 19979 19980 19981.. _int_experimental_vp_splice: 19982 19983'``llvm.experimental.vp.splice``' Intrinsic 19984^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19985 19986Syntax: 19987""""""" 19988This is an overloaded intrinsic. 19989 19990:: 19991 19992 declare <2 x double> @llvm.experimental.vp.splice.v2f64(<2 x double> %vec1, <2 x double> %vec2, i32 %imm, <2 x i1> %mask, i32 %evl1, i32 %evl2) 19993 declare <vscale x 4 x i32> @llvm.experimental.vp.splice.nxv4i32(<vscale x 4 x i32> %vec1, <vscale x 4 x i32> %vec2, i32 %imm, <vscale x 4 x i1> %mask, i32 %evl1, i32 %evl2) 19994 19995Overview: 19996""""""""" 19997 19998The '``llvm.experimental.vp.splice.*``' intrinsic is the vector length 19999predicated version of the '``llvm.experimental.vector.splice.*``' intrinsic. 20000 20001Arguments: 20002"""""""""" 20003 20004The result and the first two arguments ``vec1`` and ``vec2`` are vectors with 20005the same type. The third argument ``imm`` is an immediate signed integer that 20006indicates the offset index. The fourth argument ``mask`` is a vector mask and 20007has the same number of elements as the result. The last two arguments ``evl1`` 20008and ``evl2`` are unsigned integers indicating the explicit vector lengths of 20009``vec1`` and ``vec2`` respectively. ``imm``, ``evl1`` and ``evl2`` should 20010respect the following constraints: ``-evl1 <= imm < evl1``, ``0 <= evl1 <= VL`` 20011and ``0 <= evl2 <= VL``, where ``VL`` is the runtime vector factor. If these 20012constraints are not satisfied the intrinsic has undefined behaviour. 20013 20014Semantics: 20015"""""""""" 20016 20017Effectively, this intrinsic concatenates ``vec1[0..evl1-1]`` and 20018``vec2[0..evl2-1]`` and creates the result vector by selecting the elements in a 20019window of size ``evl2``, starting at index ``imm`` (for a positive immediate) of 20020the concatenated vector. Elements in the result vector beyond ``evl2`` are 20021``undef``. If ``imm`` is negative the starting index is ``evl1 + imm``. The result 20022vector of active vector length ``evl2`` contains ``evl1 - imm`` (``-imm`` for 20023negative ``imm``) elements from indices ``[imm..evl1 - 1]`` 20024(``[evl1 + imm..evl1 -1]`` for negative ``imm``) of ``vec1`` followed by the 20025first ``evl2 - (evl1 - imm)`` (``evl2 + imm`` for negative ``imm``) elements of 20026``vec2``. If ``evl1 - imm`` (``-imm``) >= ``evl2``, only the first ``evl2`` 20027elements are considered and the remaining are ``undef``. The lanes in the result 20028vector disabled by ``mask`` are ``undef``. 20029 20030Examples: 20031""""""""" 20032 20033.. code-block:: text 20034 20035 llvm.experimental.vp.splice(<A,B,C,D>, <E,F,G,H>, 1, 2, 3) ==> <B, E, F, undef> ; index 20036 llvm.experimental.vp.splice(<A,B,C,D>, <E,F,G,H>, -2, 3, 2) ==> <B, C, undef, undef> ; trailing elements 20037 20038 20039.. _int_vp_load: 20040 20041'``llvm.vp.load``' Intrinsic 20042^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20043 20044Syntax: 20045""""""" 20046This is an overloaded intrinsic. 20047 20048:: 20049 20050 declare <4 x float> @llvm.vp.load.v4f32.p0(ptr %ptr, <4 x i1> %mask, i32 %evl) 20051 declare <vscale x 2 x i16> @llvm.vp.load.nxv2i16.p0(ptr %ptr, <vscale x 2 x i1> %mask, i32 %evl) 20052 declare <8 x float> @llvm.vp.load.v8f32.p1(ptr addrspace(1) %ptr, <8 x i1> %mask, i32 %evl) 20053 declare <vscale x 1 x i64> @llvm.vp.load.nxv1i64.p6(ptr addrspace(6) %ptr, <vscale x 1 x i1> %mask, i32 %evl) 20054 20055Overview: 20056""""""""" 20057 20058The '``llvm.vp.load.*``' intrinsic is the vector length predicated version of 20059the :ref:`llvm.masked.load <int_mload>` intrinsic. 20060 20061Arguments: 20062"""""""""" 20063 20064The first operand is the base pointer for the load. The second operand is a 20065vector of boolean values with the same number of elements as the return type. 20066The third is the explicit vector length of the operation. The return type and 20067underlying type of the base pointer are the same vector types. 20068 20069The :ref:`align <attr_align>` parameter attribute can be provided for the first 20070operand. 20071 20072Semantics: 20073"""""""""" 20074 20075The '``llvm.vp.load``' intrinsic reads a vector from memory in the same way as 20076the '``llvm.masked.load``' intrinsic, where the mask is taken from the 20077combination of the '``mask``' and '``evl``' operands in the usual VP way. 20078Certain '``llvm.masked.load``' operands do not have corresponding operands in 20079'``llvm.vp.load``': the '``passthru``' operand is implicitly ``undef``; the 20080'``alignment``' operand is taken as the ``align`` parameter attribute, if 20081provided. The default alignment is taken as the ABI alignment of the return 20082type as specified by the :ref:`datalayout string<langref_datalayout>`. 20083 20084Examples: 20085""""""""" 20086 20087.. code-block:: text 20088 20089 %r = call <8 x i8> @llvm.vp.load.v8i8.p0(ptr align 2 %ptr, <8 x i1> %mask, i32 %evl) 20090 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20091 20092 %also.r = call <8 x i8> @llvm.masked.load.v8i8.p0(ptr %ptr, i32 2, <8 x i1> %mask, <8 x i8> undef) 20093 20094 20095.. _int_vp_store: 20096 20097'``llvm.vp.store``' Intrinsic 20098^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20099 20100Syntax: 20101""""""" 20102This is an overloaded intrinsic. 20103 20104:: 20105 20106 declare void @llvm.vp.store.v4f32.p0(<4 x float> %val, ptr %ptr, <4 x i1> %mask, i32 %evl) 20107 declare void @llvm.vp.store.nxv2i16.p0(<vscale x 2 x i16> %val, ptr %ptr, <vscale x 2 x i1> %mask, i32 %evl) 20108 declare void @llvm.vp.store.v8f32.p1(<8 x float> %val, ptr addrspace(1) %ptr, <8 x i1> %mask, i32 %evl) 20109 declare void @llvm.vp.store.nxv1i64.p6(<vscale x 1 x i64> %val, ptr addrspace(6) %ptr, <vscale x 1 x i1> %mask, i32 %evl) 20110 20111Overview: 20112""""""""" 20113 20114The '``llvm.vp.store.*``' intrinsic is the vector length predicated version of 20115the :ref:`llvm.masked.store <int_mstore>` intrinsic. 20116 20117Arguments: 20118"""""""""" 20119 20120The first operand is the vector value to be written to memory. The second 20121operand is the base pointer for the store. It has the same underlying type as 20122the value operand. The third operand is a vector of boolean values with the 20123same number of elements as the return type. The fourth is the explicit vector 20124length of the operation. 20125 20126The :ref:`align <attr_align>` parameter attribute can be provided for the 20127second operand. 20128 20129Semantics: 20130"""""""""" 20131 20132The '``llvm.vp.store``' intrinsic reads a vector from memory in the same way as 20133the '``llvm.masked.store``' intrinsic, where the mask is taken from the 20134combination of the '``mask``' and '``evl``' operands in the usual VP way. The 20135alignment of the operation (corresponding to the '``alignment``' operand of 20136'``llvm.masked.store``') is specified by the ``align`` parameter attribute (see 20137above). If it is not provided then the ABI alignment of the type of the 20138'``value``' operand as specified by the :ref:`datalayout 20139string<langref_datalayout>` is used instead. 20140 20141Examples: 20142""""""""" 20143 20144.. code-block:: text 20145 20146 call void @llvm.vp.store.v8i8.p0(<8 x i8> %val, ptr align 4 %ptr, <8 x i1> %mask, i32 %evl) 20147 ;; For all lanes below %evl, the call above is lane-wise equivalent to the call below. 20148 20149 call void @llvm.masked.store.v8i8.p0(<8 x i8> %val, ptr %ptr, i32 4, <8 x i1> %mask) 20150 20151 20152.. _int_experimental_vp_strided_load: 20153 20154'``llvm.experimental.vp.strided.load``' Intrinsic 20155^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20156 20157Syntax: 20158""""""" 20159This is an overloaded intrinsic. 20160 20161:: 20162 20163 declare <4 x float> @llvm.experimental.vp.strided.load.v4f32.i64(ptr %ptr, i64 %stride, <4 x i1> %mask, i32 %evl) 20164 declare <vscale x 2 x i16> @llvm.experimental.vp.strided.load.nxv2i16.i64(ptr %ptr, i64 %stride, <vscale x 2 x i1> %mask, i32 %evl) 20165 20166Overview: 20167""""""""" 20168 20169The '``llvm.experimental.vp.strided.load``' intrinsic loads, into a vector, scalar values from 20170memory locations evenly spaced apart by '``stride``' number of bytes, starting from '``ptr``'. 20171 20172Arguments: 20173"""""""""" 20174 20175The first operand is the base pointer for the load. The second operand is the stride 20176value expressed in bytes. The third operand is a vector of boolean values 20177with the same number of elements as the return type. The fourth is the explicit 20178vector length of the operation. The base pointer underlying type matches the type of the scalar 20179elements of the return operand. 20180 20181The :ref:`align <attr_align>` parameter attribute can be provided for the first 20182operand. 20183 20184Semantics: 20185"""""""""" 20186 20187The '``llvm.experimental.vp.strided.load``' intrinsic loads, into a vector, multiple scalar 20188values from memory in the same way as the :ref:`llvm.vp.gather <int_vp_gather>` intrinsic, 20189where the vector of pointers is in the form: 20190 20191 ``%ptrs = <%ptr, %ptr + %stride, %ptr + 2 * %stride, ... >``, 20192 20193with '``ptr``' previously casted to a pointer '``i8``', '``stride``' always interpreted as a signed 20194integer and all arithmetic occurring in the pointer type. 20195 20196Examples: 20197""""""""" 20198 20199.. code-block:: text 20200 20201 %r = call <8 x i64> @llvm.experimental.vp.strided.load.v8i64.i64(i64* %ptr, i64 %stride, <8 x i64> %mask, i32 %evl) 20202 ;; The operation can also be expressed like this: 20203 20204 %addr = bitcast i64* %ptr to i8* 20205 ;; Create a vector of pointers %addrs in the form: 20206 ;; %addrs = <%addr, %addr + %stride, %addr + 2 * %stride, ...> 20207 %ptrs = bitcast <8 x i8* > %addrs to <8 x i64* > 20208 %also.r = call <8 x i64> @llvm.vp.gather.v8i64.v8p0i64(<8 x i64* > %ptrs, <8 x i64> %mask, i32 %evl) 20209 20210 20211.. _int_experimental_vp_strided_store: 20212 20213'``llvm.experimental.vp.strided.store``' Intrinsic 20214^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20215 20216Syntax: 20217""""""" 20218This is an overloaded intrinsic. 20219 20220:: 20221 20222 declare void @llvm.experimental.vp.strided.store.v4f32.i64(<4 x float> %val, ptr %ptr, i64 %stride, <4 x i1> %mask, i32 %evl) 20223 declare void @llvm.experimental.vp.strided.store.nxv2i16.i64(<vscale x 2 x i16> %val, ptr %ptr, i64 %stride, <vscale x 2 x i1> %mask, i32 %evl) 20224 20225Overview: 20226""""""""" 20227 20228The '``@llvm.experimental.vp.strided.store``' intrinsic stores the elements of 20229'``val``' into memory locations evenly spaced apart by '``stride``' number of 20230bytes, starting from '``ptr``'. 20231 20232Arguments: 20233"""""""""" 20234 20235The first operand is the vector value to be written to memory. The second 20236operand is the base pointer for the store. Its underlying type matches the 20237scalar element type of the value operand. The third operand is the stride value 20238expressed in bytes. The fourth operand is a vector of boolean values with the 20239same number of elements as the return type. The fifth is the explicit vector 20240length of the operation. 20241 20242The :ref:`align <attr_align>` parameter attribute can be provided for the 20243second operand. 20244 20245Semantics: 20246"""""""""" 20247 20248The '``llvm.experimental.vp.strided.store``' intrinsic stores the elements of 20249'``val``' in the same way as the :ref:`llvm.vp.scatter <int_vp_scatter>` intrinsic, 20250where the vector of pointers is in the form: 20251 20252 ``%ptrs = <%ptr, %ptr + %stride, %ptr + 2 * %stride, ... >``, 20253 20254with '``ptr``' previously casted to a pointer '``i8``', '``stride``' always interpreted as a signed 20255integer and all arithmetic occurring in the pointer type. 20256 20257Examples: 20258""""""""" 20259 20260.. code-block:: text 20261 20262 call void @llvm.experimental.vp.strided.store.v8i64.i64(<8 x i64> %val, i64* %ptr, i64 %stride, <8 x i1> %mask, i32 %evl) 20263 ;; The operation can also be expressed like this: 20264 20265 %addr = bitcast i64* %ptr to i8* 20266 ;; Create a vector of pointers %addrs in the form: 20267 ;; %addrs = <%addr, %addr + %stride, %addr + 2 * %stride, ...> 20268 %ptrs = bitcast <8 x i8* > %addrs to <8 x i64* > 20269 call void @llvm.vp.scatter.v8i64.v8p0i64(<8 x i64> %val, <8 x i64*> %ptrs, <8 x i1> %mask, i32 %evl) 20270 20271 20272.. _int_vp_gather: 20273 20274'``llvm.vp.gather``' Intrinsic 20275^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20276 20277Syntax: 20278""""""" 20279This is an overloaded intrinsic. 20280 20281:: 20282 20283 declare <4 x double> @llvm.vp.gather.v4f64.v4p0(<4 x ptr> %ptrs, <4 x i1> %mask, i32 %evl) 20284 declare <vscale x 2 x i8> @llvm.vp.gather.nxv2i8.nxv2p0(<vscale x 2 x ptr> %ptrs, <vscale x 2 x i1> %mask, i32 %evl) 20285 declare <2 x float> @llvm.vp.gather.v2f32.v2p2(<2 x ptr addrspace(2)> %ptrs, <2 x i1> %mask, i32 %evl) 20286 declare <vscale x 4 x i32> @llvm.vp.gather.nxv4i32.nxv4p4(<vscale x 4 x ptr addrspace(4)> %ptrs, <vscale x 4 x i1> %mask, i32 %evl) 20287 20288Overview: 20289""""""""" 20290 20291The '``llvm.vp.gather.*``' intrinsic is the vector length predicated version of 20292the :ref:`llvm.masked.gather <int_mgather>` intrinsic. 20293 20294Arguments: 20295"""""""""" 20296 20297The first operand is a vector of pointers which holds all memory addresses to 20298read. The second operand is a vector of boolean values with the same number of 20299elements as the return type. The third is the explicit vector length of the 20300operation. The return type and underlying type of the vector of pointers are 20301the same vector types. 20302 20303The :ref:`align <attr_align>` parameter attribute can be provided for the first 20304operand. 20305 20306Semantics: 20307"""""""""" 20308 20309The '``llvm.vp.gather``' intrinsic reads multiple scalar values from memory in 20310the same way as the '``llvm.masked.gather``' intrinsic, where the mask is taken 20311from the combination of the '``mask``' and '``evl``' operands in the usual VP 20312way. Certain '``llvm.masked.gather``' operands do not have corresponding 20313operands in '``llvm.vp.gather``': the '``passthru``' operand is implicitly 20314``undef``; the '``alignment``' operand is taken as the ``align`` parameter, if 20315provided. The default alignment is taken as the ABI alignment of the source 20316addresses as specified by the :ref:`datalayout string<langref_datalayout>`. 20317 20318Examples: 20319""""""""" 20320 20321.. code-block:: text 20322 20323 %r = call <8 x i8> @llvm.vp.gather.v8i8.v8p0(<8 x ptr> align 8 %ptrs, <8 x i1> %mask, i32 %evl) 20324 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20325 20326 %also.r = call <8 x i8> @llvm.masked.gather.v8i8.v8p0(<8 x ptr> %ptrs, i32 8, <8 x i1> %mask, <8 x i8> undef) 20327 20328 20329.. _int_vp_scatter: 20330 20331'``llvm.vp.scatter``' Intrinsic 20332^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20333 20334Syntax: 20335""""""" 20336This is an overloaded intrinsic. 20337 20338:: 20339 20340 declare void @llvm.vp.scatter.v4f64.v4p0(<4 x double> %val, <4 x ptr> %ptrs, <4 x i1> %mask, i32 %evl) 20341 declare void @llvm.vp.scatter.nxv2i8.nxv2p0(<vscale x 2 x i8> %val, <vscale x 2 x ptr> %ptrs, <vscale x 2 x i1> %mask, i32 %evl) 20342 declare void @llvm.vp.scatter.v2f32.v2p2(<2 x float> %val, <2 x ptr addrspace(2)> %ptrs, <2 x i1> %mask, i32 %evl) 20343 declare void @llvm.vp.scatter.nxv4i32.nxv4p4(<vscale x 4 x i32> %val, <vscale x 4 x ptr addrspace(4)> %ptrs, <vscale x 4 x i1> %mask, i32 %evl) 20344 20345Overview: 20346""""""""" 20347 20348The '``llvm.vp.scatter.*``' intrinsic is the vector length predicated version of 20349the :ref:`llvm.masked.scatter <int_mscatter>` intrinsic. 20350 20351Arguments: 20352"""""""""" 20353 20354The first operand is a vector value to be written to memory. The second operand 20355is a vector of pointers, pointing to where the value elements should be stored. 20356The third operand is a vector of boolean values with the same number of 20357elements as the return type. The fourth is the explicit vector length of the 20358operation. 20359 20360The :ref:`align <attr_align>` parameter attribute can be provided for the 20361second operand. 20362 20363Semantics: 20364"""""""""" 20365 20366The '``llvm.vp.scatter``' intrinsic writes multiple scalar values to memory in 20367the same way as the '``llvm.masked.scatter``' intrinsic, where the mask is 20368taken from the combination of the '``mask``' and '``evl``' operands in the 20369usual VP way. The '``alignment``' operand of the '``llvm.masked.scatter``' does 20370not have a corresponding operand in '``llvm.vp.scatter``': it is instead 20371provided via the optional ``align`` parameter attribute on the 20372vector-of-pointers operand. Otherwise it is taken as the ABI alignment of the 20373destination addresses as specified by the :ref:`datalayout 20374string<langref_datalayout>`. 20375 20376Examples: 20377""""""""" 20378 20379.. code-block:: text 20380 20381 call void @llvm.vp.scatter.v8i8.v8p0(<8 x i8> %val, <8 x ptr> align 1 %ptrs, <8 x i1> %mask, i32 %evl) 20382 ;; For all lanes below %evl, the call above is lane-wise equivalent to the call below. 20383 20384 call void @llvm.masked.scatter.v8i8.v8p0(<8 x i8> %val, <8 x ptr> %ptrs, i32 1, <8 x i1> %mask) 20385 20386 20387.. _int_vp_trunc: 20388 20389'``llvm.vp.trunc.*``' Intrinsics 20390^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20391 20392Syntax: 20393""""""" 20394This is an overloaded intrinsic. 20395 20396:: 20397 20398 declare <16 x i16> @llvm.vp.trunc.v16i16.v16i32 (<16 x i32> <op>, <16 x i1> <mask>, i32 <vector_length>) 20399 declare <vscale x 4 x i16> @llvm.vp.trunc.nxv4i16.nxv4i32 (<vscale x 4 x i32> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20400 20401Overview: 20402""""""""" 20403 20404The '``llvm.vp.trunc``' intrinsic truncates its first operand to the return 20405type. The operation has a mask and an explicit vector length parameter. 20406 20407 20408Arguments: 20409"""""""""" 20410 20411The '``llvm.vp.trunc``' intrinsic takes a value to cast as its first operand. 20412The return type is the type to cast the value to. Both types must be vector of 20413:ref:`integer <t_integer>` type. The bit size of the value must be larger than 20414the bit size of the return type. The second operand is the vector mask. The 20415return type, the value to cast, and the vector mask have the same number of 20416elements. The third operand is the explicit vector length of the operation. 20417 20418Semantics: 20419"""""""""" 20420 20421The '``llvm.vp.trunc``' intrinsic truncates the high order bits in value and 20422converts the remaining bits to return type. Since the source size must be larger 20423than the destination size, '``llvm.vp.trunc``' cannot be a *no-op cast*. It will 20424always truncate bits. The conversion is performed on lane positions below the 20425explicit vector length and where the vector mask is true. Masked-off lanes are 20426undefined. 20427 20428Examples: 20429""""""""" 20430 20431.. code-block:: llvm 20432 20433 %r = call <4 x i16> @llvm.vp.trunc.v4i16.v4i32(<4 x i32> %a, <4 x i1> %mask, i32 %evl) 20434 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20435 20436 %t = trunc <4 x i32> %a to <4 x i16> 20437 %also.r = select <4 x i1> %mask, <4 x i16> %t, <4 x i16> undef 20438 20439 20440.. _int_vp_zext: 20441 20442'``llvm.vp.zext.*``' Intrinsics 20443^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20444 20445Syntax: 20446""""""" 20447This is an overloaded intrinsic. 20448 20449:: 20450 20451 declare <16 x i32> @llvm.vp.zext.v16i32.v16i16 (<16 x i16> <op>, <16 x i1> <mask>, i32 <vector_length>) 20452 declare <vscale x 4 x i32> @llvm.vp.zext.nxv4i32.nxv4i16 (<vscale x 4 x i16> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20453 20454Overview: 20455""""""""" 20456 20457The '``llvm.vp.zext``' intrinsic zero extends its first operand to the return 20458type. The operation has a mask and an explicit vector length parameter. 20459 20460 20461Arguments: 20462"""""""""" 20463 20464The '``llvm.vp.zext``' intrinsic takes a value to cast as its first operand. 20465The return type is the type to cast the value to. Both types must be vectors of 20466:ref:`integer <t_integer>` type. The bit size of the value must be smaller than 20467the bit size of the return type. The second operand is the vector mask. The 20468return type, the value to cast, and the vector mask have the same number of 20469elements. The third operand is the explicit vector length of the operation. 20470 20471Semantics: 20472"""""""""" 20473 20474The '``llvm.vp.zext``' intrinsic fill the high order bits of the value with zero 20475bits until it reaches the size of the return type. When zero extending from i1, 20476the result will always be either 0 or 1. The conversion is performed on lane 20477positions below the explicit vector length and where the vector mask is true. 20478Masked-off lanes are undefined. 20479 20480Examples: 20481""""""""" 20482 20483.. code-block:: llvm 20484 20485 %r = call <4 x i32> @llvm.vp.zext.v4i32.v4i16(<4 x i16> %a, <4 x i1> %mask, i32 %evl) 20486 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20487 20488 %t = zext <4 x i16> %a to <4 x i32> 20489 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 20490 20491 20492.. _int_vp_sext: 20493 20494'``llvm.vp.sext.*``' Intrinsics 20495^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20496 20497Syntax: 20498""""""" 20499This is an overloaded intrinsic. 20500 20501:: 20502 20503 declare <16 x i32> @llvm.vp.sext.v16i32.v16i16 (<16 x i16> <op>, <16 x i1> <mask>, i32 <vector_length>) 20504 declare <vscale x 4 x i32> @llvm.vp.sext.nxv4i32.nxv4i16 (<vscale x 4 x i16> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20505 20506Overview: 20507""""""""" 20508 20509The '``llvm.vp.sext``' intrinsic sign extends its first operand to the return 20510type. The operation has a mask and an explicit vector length parameter. 20511 20512 20513Arguments: 20514"""""""""" 20515 20516The '``llvm.vp.sext``' intrinsic takes a value to cast as its first operand. 20517The return type is the type to cast the value to. Both types must be vectors of 20518:ref:`integer <t_integer>` type. The bit size of the value must be smaller than 20519the bit size of the return type. The second operand is the vector mask. The 20520return type, the value to cast, and the vector mask have the same number of 20521elements. The third operand is the explicit vector length of the operation. 20522 20523Semantics: 20524"""""""""" 20525 20526The '``llvm.vp.sext``' intrinsic performs a sign extension by copying the sign 20527bit (highest order bit) of the value until it reaches the size of the return 20528type. When zero extending from i1, the result will always be either -1 or 0. 20529The conversion is performed on lane positions below the explicit vector length 20530and where the vector mask is true. Masked-off lanes are undefined. 20531 20532Examples: 20533""""""""" 20534 20535.. code-block:: llvm 20536 20537 %r = call <4 x i32> @llvm.vp.sext.v4i32.v4i16(<4 x i16> %a, <4 x i1> %mask, i32 %evl) 20538 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20539 20540 %t = sext <4 x i16> %a to <4 x i32> 20541 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 20542 20543 20544.. _int_vp_fptrunc: 20545 20546'``llvm.vp.fptrunc.*``' Intrinsics 20547^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20548 20549Syntax: 20550""""""" 20551This is an overloaded intrinsic. 20552 20553:: 20554 20555 declare <16 x float> @llvm.vp.fptrunc.v16f32.v16f64 (<16 x double> <op>, <16 x i1> <mask>, i32 <vector_length>) 20556 declare <vscale x 4 x float> @llvm.vp.trunc.nxv4f32.nxv4f64 (<vscale x 4 x double> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20557 20558Overview: 20559""""""""" 20560 20561The '``llvm.vp.fptrunc``' intrinsic truncates its first operand to the return 20562type. The operation has a mask and an explicit vector length parameter. 20563 20564 20565Arguments: 20566"""""""""" 20567 20568The '``llvm.vp.fptrunc``' intrinsic takes a value to cast as its first operand. 20569The return type is the type to cast the value to. Both types must be vector of 20570:ref:`floating-point <t_floating>` type. The bit size of the value must be 20571larger than the bit size of the return type. This implies that 20572'``llvm.vp.fptrunc``' cannot be used to make a *no-op cast*. The second operand 20573is the vector mask. The return type, the value to cast, and the vector mask have 20574the same number of elements. The third operand is the explicit vector length of 20575the operation. 20576 20577Semantics: 20578"""""""""" 20579 20580The '``llvm.vp.fptrunc``' intrinsic casts a ``value`` from a larger 20581:ref:`floating-point <t_floating>` type to a smaller :ref:`floating-point 20582<t_floating>` type. 20583This instruction is assumed to execute in the default :ref:`floating-point 20584environment <floatenv>`. The conversion is performed on lane positions below the 20585explicit vector length and where the vector mask is true. Masked-off lanes are 20586undefined. 20587 20588Examples: 20589""""""""" 20590 20591.. code-block:: llvm 20592 20593 %r = call <4 x float> @llvm.vp.fptrunc.v4f32.v4f64(<4 x double> %a, <4 x i1> %mask, i32 %evl) 20594 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20595 20596 %t = fptrunc <4 x double> %a to <4 x float> 20597 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 20598 20599 20600.. _int_vp_fpext: 20601 20602'``llvm.vp.fpext.*``' Intrinsics 20603^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20604 20605Syntax: 20606""""""" 20607This is an overloaded intrinsic. 20608 20609:: 20610 20611 declare <16 x double> @llvm.vp.fpext.v16f64.v16f32 (<16 x float> <op>, <16 x i1> <mask>, i32 <vector_length>) 20612 declare <vscale x 4 x double> @llvm.vp.fpext.nxv4f64.nxv4f32 (<vscale x 4 x float> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20613 20614Overview: 20615""""""""" 20616 20617The '``llvm.vp.fpext``' intrinsic extends its first operand to the return 20618type. The operation has a mask and an explicit vector length parameter. 20619 20620 20621Arguments: 20622"""""""""" 20623 20624The '``llvm.vp.fpext``' intrinsic takes a value to cast as its first operand. 20625The return type is the type to cast the value to. Both types must be vector of 20626:ref:`floating-point <t_floating>` type. The bit size of the value must be 20627smaller than the bit size of the return type. This implies that 20628'``llvm.vp.fpext``' cannot be used to make a *no-op cast*. The second operand 20629is the vector mask. The return type, the value to cast, and the vector mask have 20630the same number of elements. The third operand is the explicit vector length of 20631the operation. 20632 20633Semantics: 20634"""""""""" 20635 20636The '``llvm.vp.fpext``' intrinsic extends the ``value`` from a smaller 20637:ref:`floating-point <t_floating>` type to a larger :ref:`floating-point 20638<t_floating>` type. The '``llvm.vp.fpext``' cannot be used to make a 20639*no-op cast* because it always changes bits. Use ``bitcast`` to make a 20640*no-op cast* for a floating-point cast. 20641The conversion is performed on lane positions below the explicit vector length 20642and where the vector mask is true. Masked-off lanes are undefined. 20643 20644Examples: 20645""""""""" 20646 20647.. code-block:: llvm 20648 20649 %r = call <4 x double> @llvm.vp.fpext.v4f64.v4f32(<4 x float> %a, <4 x i1> %mask, i32 %evl) 20650 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20651 20652 %t = fpext <4 x float> %a to <4 x double> 20653 %also.r = select <4 x i1> %mask, <4 x double> %t, <4 x double> undef 20654 20655 20656.. _int_vp_fptoui: 20657 20658'``llvm.vp.fptoui.*``' Intrinsics 20659^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20660 20661Syntax: 20662""""""" 20663This is an overloaded intrinsic. 20664 20665:: 20666 20667 declare <16 x i32> @llvm.vp.fptoui.v16i32.v16f32 (<16 x float> <op>, <16 x i1> <mask>, i32 <vector_length>) 20668 declare <vscale x 4 x i32> @llvm.vp.fptoui.nxv4i32.nxv4f32 (<vscale x 4 x float> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20669 declare <256 x i64> @llvm.vp.fptoui.v256i64.v256f64 (<256 x double> <op>, <256 x i1> <mask>, i32 <vector_length>) 20670 20671Overview: 20672""""""""" 20673 20674The '``llvm.vp.fptoui``' intrinsic converts the :ref:`floating-point 20675<t_floating>` operand to the unsigned integer return type. 20676The operation has a mask and an explicit vector length parameter. 20677 20678 20679Arguments: 20680"""""""""" 20681 20682The '``llvm.vp.fptoui``' intrinsic takes a value to cast as its first operand. 20683The value to cast must be a vector of :ref:`floating-point <t_floating>` type. 20684The return type is the type to cast the value to. The return type must be 20685vector of :ref:`integer <t_integer>` type. The second operand is the vector 20686mask. The return type, the value to cast, and the vector mask have the same 20687number of elements. The third operand is the explicit vector length of the 20688operation. 20689 20690Semantics: 20691"""""""""" 20692 20693The '``llvm.vp.fptoui``' intrinsic converts its :ref:`floating-point 20694<t_floating>` operand into the nearest (rounding towards zero) unsigned integer 20695value where the lane position is below the explicit vector length and the 20696vector mask is true. Masked-off lanes are undefined. On enabled lanes where 20697conversion takes place and the value cannot fit in the return type, the result 20698on that lane is a :ref:`poison value <poisonvalues>`. 20699 20700Examples: 20701""""""""" 20702 20703.. code-block:: llvm 20704 20705 %r = call <4 x i32> @llvm.vp.fptoui.v4i32.v4f32(<4 x float> %a, <4 x i1> %mask, i32 %evl) 20706 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20707 20708 %t = fptoui <4 x float> %a to <4 x i32> 20709 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 20710 20711 20712.. _int_vp_fptosi: 20713 20714'``llvm.vp.fptosi.*``' Intrinsics 20715^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20716 20717Syntax: 20718""""""" 20719This is an overloaded intrinsic. 20720 20721:: 20722 20723 declare <16 x i32> @llvm.vp.fptosi.v16i32.v16f32 (<16 x float> <op>, <16 x i1> <mask>, i32 <vector_length>) 20724 declare <vscale x 4 x i32> @llvm.vp.fptosi.nxv4i32.nxv4f32 (<vscale x 4 x float> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20725 declare <256 x i64> @llvm.vp.fptosi.v256i64.v256f64 (<256 x double> <op>, <256 x i1> <mask>, i32 <vector_length>) 20726 20727Overview: 20728""""""""" 20729 20730The '``llvm.vp.fptosi``' intrinsic converts the :ref:`floating-point 20731<t_floating>` operand to the signed integer return type. 20732The operation has a mask and an explicit vector length parameter. 20733 20734 20735Arguments: 20736"""""""""" 20737 20738The '``llvm.vp.fptosi``' intrinsic takes a value to cast as its first operand. 20739The value to cast must be a vector of :ref:`floating-point <t_floating>` type. 20740The return type is the type to cast the value to. The return type must be 20741vector of :ref:`integer <t_integer>` type. The second operand is the vector 20742mask. The return type, the value to cast, and the vector mask have the same 20743number of elements. The third operand is the explicit vector length of the 20744operation. 20745 20746Semantics: 20747"""""""""" 20748 20749The '``llvm.vp.fptosi``' intrinsic converts its :ref:`floating-point 20750<t_floating>` operand into the nearest (rounding towards zero) signed integer 20751value where the lane position is below the explicit vector length and the 20752vector mask is true. Masked-off lanes are undefined. On enabled lanes where 20753conversion takes place and the value cannot fit in the return type, the result 20754on that lane is a :ref:`poison value <poisonvalues>`. 20755 20756Examples: 20757""""""""" 20758 20759.. code-block:: llvm 20760 20761 %r = call <4 x i32> @llvm.vp.fptosi.v4i32.v4f32(<4 x float> %a, <4 x i1> %mask, i32 %evl) 20762 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20763 20764 %t = fptosi <4 x float> %a to <4 x i32> 20765 %also.r = select <4 x i1> %mask, <4 x i32> %t, <4 x i32> undef 20766 20767 20768.. _int_vp_uitofp: 20769 20770'``llvm.vp.uitofp.*``' Intrinsics 20771^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20772 20773Syntax: 20774""""""" 20775This is an overloaded intrinsic. 20776 20777:: 20778 20779 declare <16 x float> @llvm.vp.uitofp.v16f32.v16i32 (<16 x i32> <op>, <16 x i1> <mask>, i32 <vector_length>) 20780 declare <vscale x 4 x float> @llvm.vp.uitofp.nxv4f32.nxv4i32 (<vscale x 4 x i32> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20781 declare <256 x double> @llvm.vp.uitofp.v256f64.v256i64 (<256 x i64> <op>, <256 x i1> <mask>, i32 <vector_length>) 20782 20783Overview: 20784""""""""" 20785 20786The '``llvm.vp.uitofp``' intrinsic converts its unsigned integer operand to the 20787:ref:`floating-point <t_floating>` return type. The operation has a mask and 20788an explicit vector length parameter. 20789 20790 20791Arguments: 20792"""""""""" 20793 20794The '``llvm.vp.uitofp``' intrinsic takes a value to cast as its first operand. 20795The value to cast must be vector of :ref:`integer <t_integer>` type. The 20796return type is the type to cast the value to. The return type must be a vector 20797of :ref:`floating-point <t_floating>` type. The second operand is the vector 20798mask. The return type, the value to cast, and the vector mask have the same 20799number of elements. The third operand is the explicit vector length of the 20800operation. 20801 20802Semantics: 20803"""""""""" 20804 20805The '``llvm.vp.uitofp``' intrinsic interprets its first operand as an unsigned 20806integer quantity and converts it to the corresponding floating-point value. If 20807the value cannot be exactly represented, it is rounded using the default 20808rounding mode. The conversion is performed on lane positions below the 20809explicit vector length and where the vector mask is true. Masked-off lanes are 20810undefined. 20811 20812Examples: 20813""""""""" 20814 20815.. code-block:: llvm 20816 20817 %r = call <4 x float> @llvm.vp.uitofp.v4f32.v4i32(<4 x i32> %a, <4 x i1> %mask, i32 %evl) 20818 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20819 20820 %t = uitofp <4 x i32> %a to <4 x float> 20821 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 20822 20823 20824.. _int_vp_sitofp: 20825 20826'``llvm.vp.sitofp.*``' Intrinsics 20827^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20828 20829Syntax: 20830""""""" 20831This is an overloaded intrinsic. 20832 20833:: 20834 20835 declare <16 x float> @llvm.vp.sitofp.v16f32.v16i32 (<16 x i32> <op>, <16 x i1> <mask>, i32 <vector_length>) 20836 declare <vscale x 4 x float> @llvm.vp.sitofp.nxv4f32.nxv4i32 (<vscale x 4 x i32> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20837 declare <256 x double> @llvm.vp.sitofp.v256f64.v256i64 (<256 x i64> <op>, <256 x i1> <mask>, i32 <vector_length>) 20838 20839Overview: 20840""""""""" 20841 20842The '``llvm.vp.sitofp``' intrinsic converts its signed integer operand to the 20843:ref:`floating-point <t_floating>` return type. The operation has a mask and 20844an explicit vector length parameter. 20845 20846 20847Arguments: 20848"""""""""" 20849 20850The '``llvm.vp.sitofp``' intrinsic takes a value to cast as its first operand. 20851The value to cast must be vector of :ref:`integer <t_integer>` type. The 20852return type is the type to cast the value to. The return type must be a vector 20853of :ref:`floating-point <t_floating>` type. The second operand is the vector 20854mask. The return type, the value to cast, and the vector mask have the same 20855number of elements. The third operand is the explicit vector length of the 20856operation. 20857 20858Semantics: 20859"""""""""" 20860 20861The '``llvm.vp.sitofp``' intrinsic interprets its first operand as a signed 20862integer quantity and converts it to the corresponding floating-point value. If 20863the value cannot be exactly represented, it is rounded using the default 20864rounding mode. The conversion is performed on lane positions below the 20865explicit vector length and where the vector mask is true. Masked-off lanes are 20866undefined. 20867 20868Examples: 20869""""""""" 20870 20871.. code-block:: llvm 20872 20873 %r = call <4 x float> @llvm.vp.sitofp.v4f32.v4i32(<4 x i32> %a, <4 x i1> %mask, i32 %evl) 20874 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20875 20876 %t = sitofp <4 x i32> %a to <4 x float> 20877 %also.r = select <4 x i1> %mask, <4 x float> %t, <4 x float> undef 20878 20879 20880.. _int_vp_ptrtoint: 20881 20882'``llvm.vp.ptrtoint.*``' Intrinsics 20883^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20884 20885Syntax: 20886""""""" 20887This is an overloaded intrinsic. 20888 20889:: 20890 20891 declare <16 x i8> @llvm.vp.ptrtoint.v16i8.v16p0(<16 x ptr> <op>, <16 x i1> <mask>, i32 <vector_length>) 20892 declare <vscale x 4 x i8> @llvm.vp.ptrtoint.nxv4i8.nxv4p0(<vscale x 4 x ptr> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20893 declare <256 x i64> @llvm.vp.ptrtoint.v16i64.v16p0(<256 x ptr> <op>, <256 x i1> <mask>, i32 <vector_length>) 20894 20895Overview: 20896""""""""" 20897 20898The '``llvm.vp.ptrtoint``' intrinsic converts its pointer to the integer return 20899type. The operation has a mask and an explicit vector length parameter. 20900 20901 20902Arguments: 20903"""""""""" 20904 20905The '``llvm.vp.ptrtoint``' intrinsic takes a value to cast as its first operand 20906, which must be a vector of pointers, and a type to cast it to return type, 20907which must be a vector of :ref:`integer <t_integer>` type. 20908The second operand is the vector mask. The return type, the value to cast, and 20909the vector mask have the same number of elements. 20910The third operand is the explicit vector length of the operation. 20911 20912Semantics: 20913"""""""""" 20914 20915The '``llvm.vp.ptrtoint``' intrinsic converts value to return type by 20916interpreting the pointer value as an integer and either truncating or zero 20917extending that value to the size of the integer type. 20918If ``value`` is smaller than return type, then a zero extension is done. If 20919``value`` is larger than return type, then a truncation is done. If they are 20920the same size, then nothing is done (*no-op cast*) other than a type 20921change. 20922The conversion is performed on lane positions below the explicit vector length 20923and where the vector mask is true. Masked-off lanes are undefined. 20924 20925Examples: 20926""""""""" 20927 20928.. code-block:: llvm 20929 20930 %r = call <4 x i8> @llvm.vp.ptrtoint.v4i8.v4p0i32(<4 x ptr> %a, <4 x i1> %mask, i32 %evl) 20931 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20932 20933 %t = ptrtoint <4 x ptr> %a to <4 x i8> 20934 %also.r = select <4 x i1> %mask, <4 x i8> %t, <4 x i8> undef 20935 20936 20937.. _int_vp_inttoptr: 20938 20939'``llvm.vp.inttoptr.*``' Intrinsics 20940^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20941 20942Syntax: 20943""""""" 20944This is an overloaded intrinsic. 20945 20946:: 20947 20948 declare <16 x ptr> @llvm.vp.inttoptr.v16p0.v16i32 (<16 x i32> <op>, <16 x i1> <mask>, i32 <vector_length>) 20949 declare <vscale x 4 x ptr> @llvm.vp.inttoptr.nxv4p0.nxv4i32 (<vscale x 4 x i32> <op>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 20950 declare <256 x ptr> @llvm.vp.inttoptr.v256p0.v256i32 (<256 x i32> <op>, <256 x i1> <mask>, i32 <vector_length>) 20951 20952Overview: 20953""""""""" 20954 20955The '``llvm.vp.inttoptr``' intrinsic converts its integer value to the point 20956return type. The operation has a mask and an explicit vector length parameter. 20957 20958 20959Arguments: 20960"""""""""" 20961 20962The '``llvm.vp.inttoptr``' intrinsic takes a value to cast as its first operand 20963, which must be a vector of :ref:`integer <t_integer>` type, and a type to cast 20964it to return type, which must be a vector of pointers type. 20965The second operand is the vector mask. The return type, the value to cast, and 20966the vector mask have the same number of elements. 20967The third operand is the explicit vector length of the operation. 20968 20969Semantics: 20970"""""""""" 20971 20972The '``llvm.vp.inttoptr``' intrinsic converts ``value`` to return type by 20973applying either a zero extension or a truncation depending on the size of the 20974integer ``value``. If ``value`` is larger than the size of a pointer, then a 20975truncation is done. If ``value`` is smaller than the size of a pointer, then a 20976zero extension is done. If they are the same size, nothing is done (*no-op cast*). 20977The conversion is performed on lane positions below the explicit vector length 20978and where the vector mask is true. Masked-off lanes are undefined. 20979 20980Examples: 20981""""""""" 20982 20983.. code-block:: llvm 20984 20985 %r = call <4 x ptr> @llvm.vp.inttoptr.v4p0i32.v4i32(<4 x i32> %a, <4 x i1> %mask, i32 %evl) 20986 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 20987 20988 %t = inttoptr <4 x i32> %a to <4 x ptr> 20989 %also.r = select <4 x i1> %mask, <4 x ptr> %t, <4 x ptr> undef 20990 20991 20992.. _int_vp_fcmp: 20993 20994'``llvm.vp.fcmp.*``' Intrinsics 20995^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 20996 20997Syntax: 20998""""""" 20999This is an overloaded intrinsic. 21000 21001:: 21002 21003 declare <16 x i1> @llvm.vp.fcmp.v16f32(<16 x float> <left_op>, <16 x float> <right_op>, metadata <condition code>, <16 x i1> <mask>, i32 <vector_length>) 21004 declare <vscale x 4 x i1> @llvm.vp.fcmp.nxv4f32(<vscale x 4 x float> <left_op>, <vscale x 4 x float> <right_op>, metadata <condition code>, <vscale x 4 x i1> <mask>, i32 <vector_length>) 21005 declare <256 x i1> @llvm.vp.fcmp.v256f64(<256 x double> <left_op>, <256 x double> <right_op>, metadata <condition code>, <256 x i1> <mask>, i32 <vector_length>) 21006 21007Overview: 21008""""""""" 21009 21010The '``llvm.vp.fcmp``' intrinsic returns a vector of boolean values based on 21011the comparison of its operands. The operation has a mask and an explicit vector 21012length parameter. 21013 21014 21015Arguments: 21016"""""""""" 21017 21018The '``llvm.vp.fcmp``' intrinsic takes the two values to compare as its first 21019and second operands. These two values must be vectors of :ref:`floating-point 21020<t_floating>` types. 21021The return type is the result of the comparison. The return type must be a 21022vector of :ref:`i1 <t_integer>` type. The fourth operand is the vector mask. 21023The return type, the values to compare, and the vector mask have the same 21024number of elements. The third operand is the condition code indicating the kind 21025of comparison to perform. It must be a metadata string with :ref:`one of the 21026supported floating-point condition code values <fcmp_md_cc>`. The fifth operand 21027is the explicit vector length of the operation. 21028 21029Semantics: 21030"""""""""" 21031 21032The '``llvm.vp.fcmp``' compares its first two operands according to the 21033condition code given as the third operand. The operands are compared element by 21034element on each enabled lane, where the the semantics of the comparison are 21035defined :ref:`according to the condition code <fcmp_md_cc_sem>`. Masked-off 21036lanes are undefined. 21037 21038Examples: 21039""""""""" 21040 21041.. code-block:: llvm 21042 21043 %r = call <4 x i1> @llvm.vp.fcmp.v4f32(<4 x float> %a, <4 x float> %b, metadata !"oeq", <4 x i1> %mask, i32 %evl) 21044 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 21045 21046 %t = fcmp oeq <4 x float> %a, %b 21047 %also.r = select <4 x i1> %mask, <4 x i1> %t, <4 x i1> undef 21048 21049 21050.. _int_vp_icmp: 21051 21052'``llvm.vp.icmp.*``' Intrinsics 21053^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21054 21055Syntax: 21056""""""" 21057This is an overloaded intrinsic. 21058 21059:: 21060 21061 declare <32 x i1> @llvm.vp.icmp.v32i32(<32 x i32> <left_op>, <32 x i32> <right_op>, metadata <condition code>, <32 x i1> <mask>, i32 <vector_length>) 21062 declare <vscale x 2 x i1> @llvm.vp.icmp.nxv2i32(<vscale x 2 x i32> <left_op>, <vscale x 2 x i32> <right_op>, metadata <condition code>, <vscale x 2 x i1> <mask>, i32 <vector_length>) 21063 declare <128 x i1> @llvm.vp.icmp.v128i8(<128 x i8> <left_op>, <128 x i8> <right_op>, metadata <condition code>, <128 x i1> <mask>, i32 <vector_length>) 21064 21065Overview: 21066""""""""" 21067 21068The '``llvm.vp.icmp``' intrinsic returns a vector of boolean values based on 21069the comparison of its operands. The operation has a mask and an explicit vector 21070length parameter. 21071 21072 21073Arguments: 21074"""""""""" 21075 21076The '``llvm.vp.icmp``' intrinsic takes the two values to compare as its first 21077and second operands. These two values must be vectors of :ref:`integer 21078<t_integer>` types. 21079The return type is the result of the comparison. The return type must be a 21080vector of :ref:`i1 <t_integer>` type. The fourth operand is the vector mask. 21081The return type, the values to compare, and the vector mask have the same 21082number of elements. The third operand is the condition code indicating the kind 21083of comparison to perform. It must be a metadata string with :ref:`one of the 21084supported integer condition code values <icmp_md_cc>`. The fifth operand is the 21085explicit vector length of the operation. 21086 21087Semantics: 21088"""""""""" 21089 21090The '``llvm.vp.icmp``' compares its first two operands according to the 21091condition code given as the third operand. The operands are compared element by 21092element on each enabled lane, where the the semantics of the comparison are 21093defined :ref:`according to the condition code <icmp_md_cc_sem>`. Masked-off 21094lanes are undefined. 21095 21096Examples: 21097""""""""" 21098 21099.. code-block:: llvm 21100 21101 %r = call <4 x i1> @llvm.vp.icmp.v4i32(<4 x i32> %a, <4 x i32> %b, metadata !"ne", <4 x i1> %mask, i32 %evl) 21102 ;; For all lanes below %evl, %r is lane-wise equivalent to %also.r 21103 21104 %t = icmp ne <4 x i32> %a, %b 21105 %also.r = select <4 x i1> %mask, <4 x i1> %t, <4 x i1> undef 21106 21107 21108.. _int_mload_mstore: 21109 21110Masked Vector Load and Store Intrinsics 21111--------------------------------------- 21112 21113LLVM 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. 21114 21115.. _int_mload: 21116 21117'``llvm.masked.load.*``' Intrinsics 21118^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21119 21120Syntax: 21121""""""" 21122This is an overloaded intrinsic. The loaded data is a vector of any integer, floating-point or pointer data type. 21123 21124:: 21125 21126 declare <16 x float> @llvm.masked.load.v16f32.p0(ptr <ptr>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>) 21127 declare <2 x double> @llvm.masked.load.v2f64.p0(ptr <ptr>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>) 21128 ;; The data is a vector of pointers 21129 declare <8 x ptr> @llvm.masked.load.v8p0.p0(ptr <ptr>, i32 <alignment>, <8 x i1> <mask>, <8 x ptr> <passthru>) 21130 21131Overview: 21132""""""""" 21133 21134Reads 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. 21135 21136 21137Arguments: 21138"""""""""" 21139 21140The 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. 21141 21142Semantics: 21143"""""""""" 21144 21145The '``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. 21146The 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. 21147 21148 21149:: 21150 21151 %res = call <16 x float> @llvm.masked.load.v16f32.p0(ptr %ptr, i32 4, <16 x i1>%mask, <16 x float> %passthru) 21152 21153 ;; The result of the two following instructions is identical aside from potential memory access exception 21154 %loadlal = load <16 x float>, ptr %ptr, align 4 21155 %res = select <16 x i1> %mask, <16 x float> %loadlal, <16 x float> %passthru 21156 21157.. _int_mstore: 21158 21159'``llvm.masked.store.*``' Intrinsics 21160^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21161 21162Syntax: 21163""""""" 21164This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type. 21165 21166:: 21167 21168 declare void @llvm.masked.store.v8i32.p0 (<8 x i32> <value>, ptr <ptr>, i32 <alignment>, <8 x i1> <mask>) 21169 declare void @llvm.masked.store.v16f32.p0(<16 x float> <value>, ptr <ptr>, i32 <alignment>, <16 x i1> <mask>) 21170 ;; The data is a vector of pointers 21171 declare void @llvm.masked.store.v8p0.p0 (<8 x ptr> <value>, ptr <ptr>, i32 <alignment>, <8 x i1> <mask>) 21172 21173Overview: 21174""""""""" 21175 21176Writes 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. 21177 21178Arguments: 21179"""""""""" 21180 21181The 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. 21182 21183 21184Semantics: 21185"""""""""" 21186 21187The '``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. 21188The 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. 21189 21190:: 21191 21192 call void @llvm.masked.store.v16f32.p0(<16 x float> %value, ptr %ptr, i32 4, <16 x i1> %mask) 21193 21194 ;; The result of the following instructions is identical aside from potential data races and memory access exceptions 21195 %oldval = load <16 x float>, ptr %ptr, align 4 21196 %res = select <16 x i1> %mask, <16 x float> %value, <16 x float> %oldval 21197 store <16 x float> %res, ptr %ptr, align 4 21198 21199 21200Masked Vector Gather and Scatter Intrinsics 21201------------------------------------------- 21202 21203LLVM 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. 21204 21205.. _int_mgather: 21206 21207'``llvm.masked.gather.*``' Intrinsics 21208^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21209 21210Syntax: 21211""""""" 21212This 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. 21213 21214:: 21215 21216 declare <16 x float> @llvm.masked.gather.v16f32.v16p0(<16 x ptr> <ptrs>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>) 21217 declare <2 x double> @llvm.masked.gather.v2f64.v2p1(<2 x ptr addrspace(1)> <ptrs>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>) 21218 declare <8 x ptr> @llvm.masked.gather.v8p0.v8p0(<8 x ptr> <ptrs>, i32 <alignment>, <8 x i1> <mask>, <8 x ptr> <passthru>) 21219 21220Overview: 21221""""""""" 21222 21223Reads 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. 21224 21225 21226Arguments: 21227"""""""""" 21228 21229The 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. 21230 21231Semantics: 21232"""""""""" 21233 21234The '``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. 21235The 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. 21236 21237 21238:: 21239 21240 %res = call <4 x double> @llvm.masked.gather.v4f64.v4p0(<4 x ptr> %ptrs, i32 8, <4 x i1> <i1 true, i1 true, i1 true, i1 true>, <4 x double> undef) 21241 21242 ;; The gather with all-true mask is equivalent to the following instruction sequence 21243 %ptr0 = extractelement <4 x ptr> %ptrs, i32 0 21244 %ptr1 = extractelement <4 x ptr> %ptrs, i32 1 21245 %ptr2 = extractelement <4 x ptr> %ptrs, i32 2 21246 %ptr3 = extractelement <4 x ptr> %ptrs, i32 3 21247 21248 %val0 = load double, ptr %ptr0, align 8 21249 %val1 = load double, ptr %ptr1, align 8 21250 %val2 = load double, ptr %ptr2, align 8 21251 %val3 = load double, ptr %ptr3, align 8 21252 21253 %vec0 = insertelement <4 x double>undef, %val0, 0 21254 %vec01 = insertelement <4 x double>%vec0, %val1, 1 21255 %vec012 = insertelement <4 x double>%vec01, %val2, 2 21256 %vec0123 = insertelement <4 x double>%vec012, %val3, 3 21257 21258.. _int_mscatter: 21259 21260'``llvm.masked.scatter.*``' Intrinsics 21261^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21262 21263Syntax: 21264""""""" 21265This 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. 21266 21267:: 21268 21269 declare void @llvm.masked.scatter.v8i32.v8p0 (<8 x i32> <value>, <8 x ptr> <ptrs>, i32 <alignment>, <8 x i1> <mask>) 21270 declare void @llvm.masked.scatter.v16f32.v16p1(<16 x float> <value>, <16 x ptr addrspace(1)> <ptrs>, i32 <alignment>, <16 x i1> <mask>) 21271 declare void @llvm.masked.scatter.v4p0.v4p0 (<4 x ptr> <value>, <4 x ptr> <ptrs>, i32 <alignment>, <4 x i1> <mask>) 21272 21273Overview: 21274""""""""" 21275 21276Writes 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. 21277 21278Arguments: 21279"""""""""" 21280 21281The 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. 21282 21283Semantics: 21284"""""""""" 21285 21286The '``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. 21287 21288:: 21289 21290 ;; This instruction unconditionally stores data vector in multiple addresses 21291 call @llvm.masked.scatter.v8i32.v8p0(<8 x i32> %value, <8 x ptr> %ptrs, i32 4, <8 x i1> <true, true, .. true>) 21292 21293 ;; It is equivalent to a list of scalar stores 21294 %val0 = extractelement <8 x i32> %value, i32 0 21295 %val1 = extractelement <8 x i32> %value, i32 1 21296 .. 21297 %val7 = extractelement <8 x i32> %value, i32 7 21298 %ptr0 = extractelement <8 x ptr> %ptrs, i32 0 21299 %ptr1 = extractelement <8 x ptr> %ptrs, i32 1 21300 .. 21301 %ptr7 = extractelement <8 x ptr> %ptrs, i32 7 21302 ;; Note: the order of the following stores is important when they overlap: 21303 store i32 %val0, ptr %ptr0, align 4 21304 store i32 %val1, ptr %ptr1, align 4 21305 .. 21306 store i32 %val7, ptr %ptr7, align 4 21307 21308 21309Masked Vector Expanding Load and Compressing Store Intrinsics 21310------------------------------------------------------------- 21311 21312LLVM 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>`. 21313 21314.. _int_expandload: 21315 21316'``llvm.masked.expandload.*``' Intrinsics 21317^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21318 21319Syntax: 21320""""""" 21321This 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. 21322 21323:: 21324 21325 declare <16 x float> @llvm.masked.expandload.v16f32 (ptr <ptr>, <16 x i1> <mask>, <16 x float> <passthru>) 21326 declare <2 x i64> @llvm.masked.expandload.v2i64 (ptr <ptr>, <2 x i1> <mask>, <2 x i64> <passthru>) 21327 21328Overview: 21329""""""""" 21330 21331Reads 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. 21332 21333 21334Arguments: 21335"""""""""" 21336 21337The 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. 21338 21339Semantics: 21340"""""""""" 21341 21342The '``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: 21343 21344.. code-block:: c 21345 21346 // In this loop we load from B and spread the elements into array A. 21347 double *A, B; int *C; 21348 for (int i = 0; i < size; ++i) { 21349 if (C[i] != 0) 21350 A[i] = B[j++]; 21351 } 21352 21353 21354.. code-block:: llvm 21355 21356 ; Load several elements from array B and expand them in a vector. 21357 ; The number of loaded elements is equal to the number of '1' elements in the Mask. 21358 %Tmp = call <8 x double> @llvm.masked.expandload.v8f64(ptr %Bptr, <8 x i1> %Mask, <8 x double> undef) 21359 ; Store the result in A 21360 call void @llvm.masked.store.v8f64.p0(<8 x double> %Tmp, ptr %Aptr, i32 8, <8 x i1> %Mask) 21361 21362 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask. 21363 %MaskI = bitcast <8 x i1> %Mask to i8 21364 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI) 21365 %MaskI64 = zext i8 %MaskIPopcnt to i64 21366 %BNextInd = add i64 %BInd, %MaskI64 21367 21368 21369Other targets may support this intrinsic differently, for example, by lowering it into a sequence of conditional scalar load operations and shuffles. 21370If all mask elements are '1', the intrinsic behavior is equivalent to the regular unmasked vector load. 21371 21372.. _int_compressstore: 21373 21374'``llvm.masked.compressstore.*``' Intrinsics 21375^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21376 21377Syntax: 21378""""""" 21379This 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. 21380 21381:: 21382 21383 declare void @llvm.masked.compressstore.v8i32 (<8 x i32> <value>, ptr <ptr>, <8 x i1> <mask>) 21384 declare void @llvm.masked.compressstore.v16f32 (<16 x float> <value>, ptr <ptr>, <16 x i1> <mask>) 21385 21386Overview: 21387""""""""" 21388 21389Selects 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. 21390 21391Arguments: 21392"""""""""" 21393 21394The 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. 21395 21396 21397Semantics: 21398"""""""""" 21399 21400The '``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: 21401 21402.. code-block:: c 21403 21404 // In this loop we load elements from A and store them consecutively in B 21405 double *A, B; int *C; 21406 for (int i = 0; i < size; ++i) { 21407 if (C[i] != 0) 21408 B[j++] = A[i] 21409 } 21410 21411 21412.. code-block:: llvm 21413 21414 ; Load elements from A. 21415 %Tmp = call <8 x double> @llvm.masked.load.v8f64.p0(ptr %Aptr, i32 8, <8 x i1> %Mask, <8 x double> undef) 21416 ; Store all selected elements consecutively in array B 21417 call <void> @llvm.masked.compressstore.v8f64(<8 x double> %Tmp, ptr %Bptr, <8 x i1> %Mask) 21418 21419 ; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask. 21420 %MaskI = bitcast <8 x i1> %Mask to i8 21421 %MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI) 21422 %MaskI64 = zext i8 %MaskIPopcnt to i64 21423 %BNextInd = add i64 %BInd, %MaskI64 21424 21425 21426Other targets may support this intrinsic differently, for example, by lowering it into a sequence of branches that guard scalar store operations. 21427 21428 21429Memory Use Markers 21430------------------ 21431 21432This class of intrinsics provides information about the 21433:ref:`lifetime of memory objects <objectlifetime>` and ranges where variables 21434are immutable. 21435 21436.. _int_lifestart: 21437 21438'``llvm.lifetime.start``' Intrinsic 21439^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21440 21441Syntax: 21442""""""" 21443 21444:: 21445 21446 declare void @llvm.lifetime.start(i64 <size>, ptr nocapture <ptr>) 21447 21448Overview: 21449""""""""" 21450 21451The '``llvm.lifetime.start``' intrinsic specifies the start of a memory 21452object's lifetime. 21453 21454Arguments: 21455"""""""""" 21456 21457The first argument is a constant integer representing the size of the 21458object, or -1 if it is variable sized. The second argument is a pointer 21459to the object. 21460 21461Semantics: 21462"""""""""" 21463 21464If ``ptr`` is a stack-allocated object and it points to the first byte of 21465the object, the object is initially marked as dead. 21466``ptr`` is conservatively considered as a non-stack-allocated object if 21467the stack coloring algorithm that is used in the optimization pipeline cannot 21468conclude that ``ptr`` is a stack-allocated object. 21469 21470After '``llvm.lifetime.start``', the stack object that ``ptr`` points is marked 21471as alive and has an uninitialized value. 21472The stack object is marked as dead when either 21473:ref:`llvm.lifetime.end <int_lifeend>` to the alloca is executed or the 21474function returns. 21475 21476After :ref:`llvm.lifetime.end <int_lifeend>` is called, 21477'``llvm.lifetime.start``' on the stack object can be called again. 21478The second '``llvm.lifetime.start``' call marks the object as alive, but it 21479does not change the address of the object. 21480 21481If ``ptr`` is a non-stack-allocated object, it does not point to the first 21482byte of the object or it is a stack object that is already alive, it simply 21483fills all bytes of the object with ``poison``. 21484 21485 21486.. _int_lifeend: 21487 21488'``llvm.lifetime.end``' Intrinsic 21489^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21490 21491Syntax: 21492""""""" 21493 21494:: 21495 21496 declare void @llvm.lifetime.end(i64 <size>, ptr nocapture <ptr>) 21497 21498Overview: 21499""""""""" 21500 21501The '``llvm.lifetime.end``' intrinsic specifies the end of a memory object's 21502lifetime. 21503 21504Arguments: 21505"""""""""" 21506 21507The first argument is a constant integer representing the size of the 21508object, or -1 if it is variable sized. The second argument is a pointer 21509to the object. 21510 21511Semantics: 21512"""""""""" 21513 21514If ``ptr`` is a stack-allocated object and it points to the first byte of the 21515object, the object is dead. 21516``ptr`` is conservatively considered as a non-stack-allocated object if 21517the stack coloring algorithm that is used in the optimization pipeline cannot 21518conclude that ``ptr`` is a stack-allocated object. 21519 21520Calling ``llvm.lifetime.end`` on an already dead alloca is no-op. 21521 21522If ``ptr`` is a non-stack-allocated object or it does not point to the first 21523byte of the object, it is equivalent to simply filling all bytes of the object 21524with ``poison``. 21525 21526 21527'``llvm.invariant.start``' Intrinsic 21528^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21529 21530Syntax: 21531""""""" 21532This is an overloaded intrinsic. The memory object can belong to any address space. 21533 21534:: 21535 21536 declare ptr @llvm.invariant.start.p0(i64 <size>, ptr nocapture <ptr>) 21537 21538Overview: 21539""""""""" 21540 21541The '``llvm.invariant.start``' intrinsic specifies that the contents of 21542a memory object will not change. 21543 21544Arguments: 21545"""""""""" 21546 21547The first argument is a constant integer representing the size of the 21548object, or -1 if it is variable sized. The second argument is a pointer 21549to the object. 21550 21551Semantics: 21552"""""""""" 21553 21554This intrinsic indicates that until an ``llvm.invariant.end`` that uses 21555the return value, the referenced memory location is constant and 21556unchanging. 21557 21558'``llvm.invariant.end``' Intrinsic 21559^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21560 21561Syntax: 21562""""""" 21563This is an overloaded intrinsic. The memory object can belong to any address space. 21564 21565:: 21566 21567 declare void @llvm.invariant.end.p0(ptr <start>, i64 <size>, ptr nocapture <ptr>) 21568 21569Overview: 21570""""""""" 21571 21572The '``llvm.invariant.end``' intrinsic specifies that the contents of a 21573memory object are mutable. 21574 21575Arguments: 21576"""""""""" 21577 21578The first argument is the matching ``llvm.invariant.start`` intrinsic. 21579The second argument is a constant integer representing the size of the 21580object, or -1 if it is variable sized and the third argument is a 21581pointer to the object. 21582 21583Semantics: 21584"""""""""" 21585 21586This intrinsic indicates that the memory is mutable again. 21587 21588'``llvm.launder.invariant.group``' Intrinsic 21589^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21590 21591Syntax: 21592""""""" 21593This is an overloaded intrinsic. The memory object can belong to any address 21594space. The returned pointer must belong to the same address space as the 21595argument. 21596 21597:: 21598 21599 declare ptr @llvm.launder.invariant.group.p0(ptr <ptr>) 21600 21601Overview: 21602""""""""" 21603 21604The '``llvm.launder.invariant.group``' intrinsic can be used when an invariant 21605established by ``invariant.group`` metadata no longer holds, to obtain a new 21606pointer value that carries fresh invariant group information. It is an 21607experimental intrinsic, which means that its semantics might change in the 21608future. 21609 21610 21611Arguments: 21612"""""""""" 21613 21614The ``llvm.launder.invariant.group`` takes only one argument, which is a pointer 21615to the memory. 21616 21617Semantics: 21618"""""""""" 21619 21620Returns another pointer that aliases its argument but which is considered different 21621for the purposes of ``load``/``store`` ``invariant.group`` metadata. 21622It does not read any accessible memory and the execution can be speculated. 21623 21624'``llvm.strip.invariant.group``' Intrinsic 21625^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21626 21627Syntax: 21628""""""" 21629This is an overloaded intrinsic. The memory object can belong to any address 21630space. The returned pointer must belong to the same address space as the 21631argument. 21632 21633:: 21634 21635 declare ptr @llvm.strip.invariant.group.p0(ptr <ptr>) 21636 21637Overview: 21638""""""""" 21639 21640The '``llvm.strip.invariant.group``' intrinsic can be used when an invariant 21641established by ``invariant.group`` metadata no longer holds, to obtain a new pointer 21642value that does not carry the invariant information. It is an experimental 21643intrinsic, which means that its semantics might change in the future. 21644 21645 21646Arguments: 21647"""""""""" 21648 21649The ``llvm.strip.invariant.group`` takes only one argument, which is a pointer 21650to the memory. 21651 21652Semantics: 21653"""""""""" 21654 21655Returns another pointer that aliases its argument but which has no associated 21656``invariant.group`` metadata. 21657It does not read any memory and can be speculated. 21658 21659 21660 21661.. _constrainedfp: 21662 21663Constrained Floating-Point Intrinsics 21664------------------------------------- 21665 21666These intrinsics are used to provide special handling of floating-point 21667operations when specific rounding mode or floating-point exception behavior is 21668required. By default, LLVM optimization passes assume that the rounding mode is 21669round-to-nearest and that floating-point exceptions will not be monitored. 21670Constrained FP intrinsics are used to support non-default rounding modes and 21671accurately preserve exception behavior without compromising LLVM's ability to 21672optimize FP code when the default behavior is used. 21673 21674If any FP operation in a function is constrained then they all must be 21675constrained. This is required for correct LLVM IR. Optimizations that 21676move code around can create miscompiles if mixing of constrained and normal 21677operations is done. The correct way to mix constrained and less constrained 21678operations is to use the rounding mode and exception handling metadata to 21679mark constrained intrinsics as having LLVM's default behavior. 21680 21681Each of these intrinsics corresponds to a normal floating-point operation. The 21682data arguments and the return value are the same as the corresponding FP 21683operation. 21684 21685The rounding mode argument is a metadata string specifying what 21686assumptions, if any, the optimizer can make when transforming constant 21687values. Some constrained FP intrinsics omit this argument. If required 21688by the intrinsic, this argument must be one of the following strings: 21689 21690:: 21691 21692 "round.dynamic" 21693 "round.tonearest" 21694 "round.downward" 21695 "round.upward" 21696 "round.towardzero" 21697 "round.tonearestaway" 21698 21699If this argument is "round.dynamic" optimization passes must assume that the 21700rounding mode is unknown and may change at runtime. No transformations that 21701depend on rounding mode may be performed in this case. 21702 21703The other possible values for the rounding mode argument correspond to the 21704similarly named IEEE rounding modes. If the argument is any of these values 21705optimization passes may perform transformations as long as they are consistent 21706with the specified rounding mode. 21707 21708For example, 'x-0'->'x' is not a valid transformation if the rounding mode is 21709"round.downward" or "round.dynamic" because if the value of 'x' is +0 then 21710'x-0' should evaluate to '-0' when rounding downward. However, this 21711transformation is legal for all other rounding modes. 21712 21713For values other than "round.dynamic" optimization passes may assume that the 21714actual runtime rounding mode (as defined in a target-specific manner) matches 21715the specified rounding mode, but this is not guaranteed. Using a specific 21716non-dynamic rounding mode which does not match the actual rounding mode at 21717runtime results in undefined behavior. 21718 21719The exception behavior argument is a metadata string describing the floating 21720point exception semantics that required for the intrinsic. This argument 21721must be one of the following strings: 21722 21723:: 21724 21725 "fpexcept.ignore" 21726 "fpexcept.maytrap" 21727 "fpexcept.strict" 21728 21729If this argument is "fpexcept.ignore" optimization passes may assume that the 21730exception status flags will not be read and that floating-point exceptions will 21731be masked. This allows transformations to be performed that may change the 21732exception semantics of the original code. For example, FP operations may be 21733speculatively executed in this case whereas they must not be for either of the 21734other possible values of this argument. 21735 21736If the exception behavior argument is "fpexcept.maytrap" optimization passes 21737must avoid transformations that may raise exceptions that would not have been 21738raised by the original code (such as speculatively executing FP operations), but 21739passes are not required to preserve all exceptions that are implied by the 21740original code. For example, exceptions may be potentially hidden by constant 21741folding. 21742 21743If the exception behavior argument is "fpexcept.strict" all transformations must 21744strictly preserve the floating-point exception semantics of the original code. 21745Any FP exception that would have been raised by the original code must be raised 21746by the transformed code, and the transformed code must not raise any FP 21747exceptions that would not have been raised by the original code. This is the 21748exception behavior argument that will be used if the code being compiled reads 21749the FP exception status flags, but this mode can also be used with code that 21750unmasks FP exceptions. 21751 21752The number and order of floating-point exceptions is NOT guaranteed. For 21753example, a series of FP operations that each may raise exceptions may be 21754vectorized into a single instruction that raises each unique exception a single 21755time. 21756 21757Proper :ref:`function attributes <fnattrs>` usage is required for the 21758constrained intrinsics to function correctly. 21759 21760All function *calls* done in a function that uses constrained floating 21761point intrinsics must have the ``strictfp`` attribute. 21762 21763All function *definitions* that use constrained floating point intrinsics 21764must have the ``strictfp`` attribute. 21765 21766'``llvm.experimental.constrained.fadd``' Intrinsic 21767^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21768 21769Syntax: 21770""""""" 21771 21772:: 21773 21774 declare <type> 21775 @llvm.experimental.constrained.fadd(<type> <op1>, <type> <op2>, 21776 metadata <rounding mode>, 21777 metadata <exception behavior>) 21778 21779Overview: 21780""""""""" 21781 21782The '``llvm.experimental.constrained.fadd``' intrinsic returns the sum of its 21783two operands. 21784 21785 21786Arguments: 21787"""""""""" 21788 21789The first two arguments to the '``llvm.experimental.constrained.fadd``' 21790intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 21791of floating-point values. Both arguments must have identical types. 21792 21793The third and fourth arguments specify the rounding mode and exception 21794behavior as described above. 21795 21796Semantics: 21797"""""""""" 21798 21799The value produced is the floating-point sum of the two value operands and has 21800the same type as the operands. 21801 21802 21803'``llvm.experimental.constrained.fsub``' Intrinsic 21804^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21805 21806Syntax: 21807""""""" 21808 21809:: 21810 21811 declare <type> 21812 @llvm.experimental.constrained.fsub(<type> <op1>, <type> <op2>, 21813 metadata <rounding mode>, 21814 metadata <exception behavior>) 21815 21816Overview: 21817""""""""" 21818 21819The '``llvm.experimental.constrained.fsub``' intrinsic returns the difference 21820of its two operands. 21821 21822 21823Arguments: 21824"""""""""" 21825 21826The first two arguments to the '``llvm.experimental.constrained.fsub``' 21827intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 21828of floating-point values. Both arguments must have identical types. 21829 21830The third and fourth arguments specify the rounding mode and exception 21831behavior as described above. 21832 21833Semantics: 21834"""""""""" 21835 21836The value produced is the floating-point difference of the two value operands 21837and has the same type as the operands. 21838 21839 21840'``llvm.experimental.constrained.fmul``' Intrinsic 21841^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21842 21843Syntax: 21844""""""" 21845 21846:: 21847 21848 declare <type> 21849 @llvm.experimental.constrained.fmul(<type> <op1>, <type> <op2>, 21850 metadata <rounding mode>, 21851 metadata <exception behavior>) 21852 21853Overview: 21854""""""""" 21855 21856The '``llvm.experimental.constrained.fmul``' intrinsic returns the product of 21857its two operands. 21858 21859 21860Arguments: 21861"""""""""" 21862 21863The first two arguments to the '``llvm.experimental.constrained.fmul``' 21864intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 21865of floating-point values. Both arguments must have identical types. 21866 21867The third and fourth arguments specify the rounding mode and exception 21868behavior as described above. 21869 21870Semantics: 21871"""""""""" 21872 21873The value produced is the floating-point product of the two value operands and 21874has the same type as the operands. 21875 21876 21877'``llvm.experimental.constrained.fdiv``' Intrinsic 21878^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21879 21880Syntax: 21881""""""" 21882 21883:: 21884 21885 declare <type> 21886 @llvm.experimental.constrained.fdiv(<type> <op1>, <type> <op2>, 21887 metadata <rounding mode>, 21888 metadata <exception behavior>) 21889 21890Overview: 21891""""""""" 21892 21893The '``llvm.experimental.constrained.fdiv``' intrinsic returns the quotient of 21894its two operands. 21895 21896 21897Arguments: 21898"""""""""" 21899 21900The first two arguments to the '``llvm.experimental.constrained.fdiv``' 21901intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 21902of floating-point values. Both arguments must have identical types. 21903 21904The third and fourth arguments specify the rounding mode and exception 21905behavior as described above. 21906 21907Semantics: 21908"""""""""" 21909 21910The value produced is the floating-point quotient of the two value operands and 21911has the same type as the operands. 21912 21913 21914'``llvm.experimental.constrained.frem``' Intrinsic 21915^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21916 21917Syntax: 21918""""""" 21919 21920:: 21921 21922 declare <type> 21923 @llvm.experimental.constrained.frem(<type> <op1>, <type> <op2>, 21924 metadata <rounding mode>, 21925 metadata <exception behavior>) 21926 21927Overview: 21928""""""""" 21929 21930The '``llvm.experimental.constrained.frem``' intrinsic returns the remainder 21931from the division of its two operands. 21932 21933 21934Arguments: 21935"""""""""" 21936 21937The first two arguments to the '``llvm.experimental.constrained.frem``' 21938intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 21939of floating-point values. Both arguments must have identical types. 21940 21941The third and fourth arguments specify the rounding mode and exception 21942behavior as described above. The rounding mode argument has no effect, since 21943the result of frem is never rounded, but the argument is included for 21944consistency with the other constrained floating-point intrinsics. 21945 21946Semantics: 21947"""""""""" 21948 21949The value produced is the floating-point remainder from the division of the two 21950value operands and has the same type as the operands. The remainder has the 21951same sign as the dividend. 21952 21953'``llvm.experimental.constrained.fma``' Intrinsic 21954^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21955 21956Syntax: 21957""""""" 21958 21959:: 21960 21961 declare <type> 21962 @llvm.experimental.constrained.fma(<type> <op1>, <type> <op2>, <type> <op3>, 21963 metadata <rounding mode>, 21964 metadata <exception behavior>) 21965 21966Overview: 21967""""""""" 21968 21969The '``llvm.experimental.constrained.fma``' intrinsic returns the result of a 21970fused-multiply-add operation on its operands. 21971 21972Arguments: 21973"""""""""" 21974 21975The first three arguments to the '``llvm.experimental.constrained.fma``' 21976intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector 21977<t_vector>` of floating-point values. All arguments must have identical types. 21978 21979The fourth and fifth arguments specify the rounding mode and exception behavior 21980as described above. 21981 21982Semantics: 21983"""""""""" 21984 21985The result produced is the product of the first two operands added to the third 21986operand computed with infinite precision, and then rounded to the target 21987precision. 21988 21989'``llvm.experimental.constrained.fptoui``' Intrinsic 21990^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 21991 21992Syntax: 21993""""""" 21994 21995:: 21996 21997 declare <ty2> 21998 @llvm.experimental.constrained.fptoui(<type> <value>, 21999 metadata <exception behavior>) 22000 22001Overview: 22002""""""""" 22003 22004The '``llvm.experimental.constrained.fptoui``' intrinsic converts a 22005floating-point ``value`` to its unsigned integer equivalent of type ``ty2``. 22006 22007Arguments: 22008"""""""""" 22009 22010The first argument to the '``llvm.experimental.constrained.fptoui``' 22011intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 22012<t_vector>` of floating point values. 22013 22014The second argument specifies the exception behavior as described above. 22015 22016Semantics: 22017"""""""""" 22018 22019The result produced is an unsigned integer converted from the floating 22020point operand. The value is truncated, so it is rounded towards zero. 22021 22022'``llvm.experimental.constrained.fptosi``' Intrinsic 22023^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22024 22025Syntax: 22026""""""" 22027 22028:: 22029 22030 declare <ty2> 22031 @llvm.experimental.constrained.fptosi(<type> <value>, 22032 metadata <exception behavior>) 22033 22034Overview: 22035""""""""" 22036 22037The '``llvm.experimental.constrained.fptosi``' intrinsic converts 22038:ref:`floating-point <t_floating>` ``value`` to type ``ty2``. 22039 22040Arguments: 22041"""""""""" 22042 22043The first argument to the '``llvm.experimental.constrained.fptosi``' 22044intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 22045<t_vector>` of floating point values. 22046 22047The second argument specifies the exception behavior as described above. 22048 22049Semantics: 22050"""""""""" 22051 22052The result produced is a signed integer converted from the floating 22053point operand. The value is truncated, so it is rounded towards zero. 22054 22055'``llvm.experimental.constrained.uitofp``' Intrinsic 22056^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22057 22058Syntax: 22059""""""" 22060 22061:: 22062 22063 declare <ty2> 22064 @llvm.experimental.constrained.uitofp(<type> <value>, 22065 metadata <rounding mode>, 22066 metadata <exception behavior>) 22067 22068Overview: 22069""""""""" 22070 22071The '``llvm.experimental.constrained.uitofp``' intrinsic converts an 22072unsigned integer ``value`` to a floating-point of type ``ty2``. 22073 22074Arguments: 22075"""""""""" 22076 22077The first argument to the '``llvm.experimental.constrained.uitofp``' 22078intrinsic must be an :ref:`integer <t_integer>` or :ref:`vector 22079<t_vector>` of integer values. 22080 22081The second and third arguments specify the rounding mode and exception 22082behavior as described above. 22083 22084Semantics: 22085"""""""""" 22086 22087An inexact floating-point exception will be raised if rounding is required. 22088Any result produced is a floating point value converted from the input 22089integer operand. 22090 22091'``llvm.experimental.constrained.sitofp``' Intrinsic 22092^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22093 22094Syntax: 22095""""""" 22096 22097:: 22098 22099 declare <ty2> 22100 @llvm.experimental.constrained.sitofp(<type> <value>, 22101 metadata <rounding mode>, 22102 metadata <exception behavior>) 22103 22104Overview: 22105""""""""" 22106 22107The '``llvm.experimental.constrained.sitofp``' intrinsic converts a 22108signed integer ``value`` to a floating-point of type ``ty2``. 22109 22110Arguments: 22111"""""""""" 22112 22113The first argument to the '``llvm.experimental.constrained.sitofp``' 22114intrinsic must be an :ref:`integer <t_integer>` or :ref:`vector 22115<t_vector>` of integer values. 22116 22117The second and third arguments specify the rounding mode and exception 22118behavior as described above. 22119 22120Semantics: 22121"""""""""" 22122 22123An inexact floating-point exception will be raised if rounding is required. 22124Any result produced is a floating point value converted from the input 22125integer operand. 22126 22127'``llvm.experimental.constrained.fptrunc``' Intrinsic 22128^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22129 22130Syntax: 22131""""""" 22132 22133:: 22134 22135 declare <ty2> 22136 @llvm.experimental.constrained.fptrunc(<type> <value>, 22137 metadata <rounding mode>, 22138 metadata <exception behavior>) 22139 22140Overview: 22141""""""""" 22142 22143The '``llvm.experimental.constrained.fptrunc``' intrinsic truncates ``value`` 22144to type ``ty2``. 22145 22146Arguments: 22147"""""""""" 22148 22149The first argument to the '``llvm.experimental.constrained.fptrunc``' 22150intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 22151<t_vector>` of floating point values. This argument must be larger in size 22152than the result. 22153 22154The second and third arguments specify the rounding mode and exception 22155behavior as described above. 22156 22157Semantics: 22158"""""""""" 22159 22160The result produced is a floating point value truncated to be smaller in size 22161than the operand. 22162 22163'``llvm.experimental.constrained.fpext``' Intrinsic 22164^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22165 22166Syntax: 22167""""""" 22168 22169:: 22170 22171 declare <ty2> 22172 @llvm.experimental.constrained.fpext(<type> <value>, 22173 metadata <exception behavior>) 22174 22175Overview: 22176""""""""" 22177 22178The '``llvm.experimental.constrained.fpext``' intrinsic extends a 22179floating-point ``value`` to a larger floating-point value. 22180 22181Arguments: 22182"""""""""" 22183 22184The first argument to the '``llvm.experimental.constrained.fpext``' 22185intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector 22186<t_vector>` of floating point values. This argument must be smaller in size 22187than the result. 22188 22189The second argument specifies the exception behavior as described above. 22190 22191Semantics: 22192"""""""""" 22193 22194The result produced is a floating point value extended to be larger in size 22195than the operand. All restrictions that apply to the fpext instruction also 22196apply to this intrinsic. 22197 22198'``llvm.experimental.constrained.fcmp``' and '``llvm.experimental.constrained.fcmps``' Intrinsics 22199^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22200 22201Syntax: 22202""""""" 22203 22204:: 22205 22206 declare <ty2> 22207 @llvm.experimental.constrained.fcmp(<type> <op1>, <type> <op2>, 22208 metadata <condition code>, 22209 metadata <exception behavior>) 22210 declare <ty2> 22211 @llvm.experimental.constrained.fcmps(<type> <op1>, <type> <op2>, 22212 metadata <condition code>, 22213 metadata <exception behavior>) 22214 22215Overview: 22216""""""""" 22217 22218The '``llvm.experimental.constrained.fcmp``' and 22219'``llvm.experimental.constrained.fcmps``' intrinsics return a boolean 22220value or vector of boolean values based on comparison of its operands. 22221 22222If the operands are floating-point scalars, then the result type is a 22223boolean (:ref:`i1 <t_integer>`). 22224 22225If the operands are floating-point vectors, then the result type is a 22226vector of boolean with the same number of elements as the operands being 22227compared. 22228 22229The '``llvm.experimental.constrained.fcmp``' intrinsic performs a quiet 22230comparison operation while the '``llvm.experimental.constrained.fcmps``' 22231intrinsic performs a signaling comparison operation. 22232 22233Arguments: 22234"""""""""" 22235 22236The first two arguments to the '``llvm.experimental.constrained.fcmp``' 22237and '``llvm.experimental.constrained.fcmps``' intrinsics must be 22238:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 22239of floating-point values. Both arguments must have identical types. 22240 22241The third argument is the condition code indicating the kind of comparison 22242to perform. It must be a metadata string with one of the following values: 22243 22244.. _fcmp_md_cc: 22245 22246- "``oeq``": ordered and equal 22247- "``ogt``": ordered and greater than 22248- "``oge``": ordered and greater than or equal 22249- "``olt``": ordered and less than 22250- "``ole``": ordered and less than or equal 22251- "``one``": ordered and not equal 22252- "``ord``": ordered (no nans) 22253- "``ueq``": unordered or equal 22254- "``ugt``": unordered or greater than 22255- "``uge``": unordered or greater than or equal 22256- "``ult``": unordered or less than 22257- "``ule``": unordered or less than or equal 22258- "``une``": unordered or not equal 22259- "``uno``": unordered (either nans) 22260 22261*Ordered* means that neither operand is a NAN while *unordered* means 22262that either operand may be a NAN. 22263 22264The fourth argument specifies the exception behavior as described above. 22265 22266Semantics: 22267"""""""""" 22268 22269``op1`` and ``op2`` are compared according to the condition code given 22270as the third argument. If the operands are vectors, then the 22271vectors are compared element by element. Each comparison performed 22272always yields an :ref:`i1 <t_integer>` result, as follows: 22273 22274.. _fcmp_md_cc_sem: 22275 22276- "``oeq``": yields ``true`` if both operands are not a NAN and ``op1`` 22277 is equal to ``op2``. 22278- "``ogt``": yields ``true`` if both operands are not a NAN and ``op1`` 22279 is greater than ``op2``. 22280- "``oge``": yields ``true`` if both operands are not a NAN and ``op1`` 22281 is greater than or equal to ``op2``. 22282- "``olt``": yields ``true`` if both operands are not a NAN and ``op1`` 22283 is less than ``op2``. 22284- "``ole``": yields ``true`` if both operands are not a NAN and ``op1`` 22285 is less than or equal to ``op2``. 22286- "``one``": yields ``true`` if both operands are not a NAN and ``op1`` 22287 is not equal to ``op2``. 22288- "``ord``": yields ``true`` if both operands are not a NAN. 22289- "``ueq``": yields ``true`` if either operand is a NAN or ``op1`` is 22290 equal to ``op2``. 22291- "``ugt``": yields ``true`` if either operand is a NAN or ``op1`` is 22292 greater than ``op2``. 22293- "``uge``": yields ``true`` if either operand is a NAN or ``op1`` is 22294 greater than or equal to ``op2``. 22295- "``ult``": yields ``true`` if either operand is a NAN or ``op1`` is 22296 less than ``op2``. 22297- "``ule``": yields ``true`` if either operand is a NAN or ``op1`` is 22298 less than or equal to ``op2``. 22299- "``une``": yields ``true`` if either operand is a NAN or ``op1`` is 22300 not equal to ``op2``. 22301- "``uno``": yields ``true`` if either operand is a NAN. 22302 22303The quiet comparison operation performed by 22304'``llvm.experimental.constrained.fcmp``' will only raise an exception 22305if either operand is a SNAN. The signaling comparison operation 22306performed by '``llvm.experimental.constrained.fcmps``' will raise an 22307exception if either operand is a NAN (QNAN or SNAN). Such an exception 22308does not preclude a result being produced (e.g. exception might only 22309set a flag), therefore the distinction between ordered and unordered 22310comparisons is also relevant for the 22311'``llvm.experimental.constrained.fcmps``' intrinsic. 22312 22313'``llvm.experimental.constrained.fmuladd``' Intrinsic 22314^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22315 22316Syntax: 22317""""""" 22318 22319:: 22320 22321 declare <type> 22322 @llvm.experimental.constrained.fmuladd(<type> <op1>, <type> <op2>, 22323 <type> <op3>, 22324 metadata <rounding mode>, 22325 metadata <exception behavior>) 22326 22327Overview: 22328""""""""" 22329 22330The '``llvm.experimental.constrained.fmuladd``' intrinsic represents 22331multiply-add expressions that can be fused if the code generator determines 22332that (a) the target instruction set has support for a fused operation, 22333and (b) that the fused operation is more efficient than the equivalent, 22334separate pair of mul and add instructions. 22335 22336Arguments: 22337"""""""""" 22338 22339The first three arguments to the '``llvm.experimental.constrained.fmuladd``' 22340intrinsic must be floating-point or vector of floating-point values. 22341All three arguments must have identical types. 22342 22343The fourth and fifth arguments specify the rounding mode and exception behavior 22344as described above. 22345 22346Semantics: 22347"""""""""" 22348 22349The expression: 22350 22351:: 22352 22353 %0 = call float @llvm.experimental.constrained.fmuladd.f32(%a, %b, %c, 22354 metadata <rounding mode>, 22355 metadata <exception behavior>) 22356 22357is equivalent to the expression: 22358 22359:: 22360 22361 %0 = call float @llvm.experimental.constrained.fmul.f32(%a, %b, 22362 metadata <rounding mode>, 22363 metadata <exception behavior>) 22364 %1 = call float @llvm.experimental.constrained.fadd.f32(%0, %c, 22365 metadata <rounding mode>, 22366 metadata <exception behavior>) 22367 22368except that it is unspecified whether rounding will be performed between the 22369multiplication and addition steps. Fusion is not guaranteed, even if the target 22370platform supports it. 22371If a fused multiply-add is required, the corresponding 22372:ref:`llvm.experimental.constrained.fma <int_fma>` intrinsic function should be 22373used instead. 22374This never sets errno, just as '``llvm.experimental.constrained.fma.*``'. 22375 22376Constrained libm-equivalent Intrinsics 22377-------------------------------------- 22378 22379In addition to the basic floating-point operations for which constrained 22380intrinsics are described above, there are constrained versions of various 22381operations which provide equivalent behavior to a corresponding libm function. 22382These intrinsics allow the precise behavior of these operations with respect to 22383rounding mode and exception behavior to be controlled. 22384 22385As with the basic constrained floating-point intrinsics, the rounding mode 22386and exception behavior arguments only control the behavior of the optimizer. 22387They do not change the runtime floating-point environment. 22388 22389 22390'``llvm.experimental.constrained.sqrt``' Intrinsic 22391^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22392 22393Syntax: 22394""""""" 22395 22396:: 22397 22398 declare <type> 22399 @llvm.experimental.constrained.sqrt(<type> <op1>, 22400 metadata <rounding mode>, 22401 metadata <exception behavior>) 22402 22403Overview: 22404""""""""" 22405 22406The '``llvm.experimental.constrained.sqrt``' intrinsic returns the square root 22407of the specified value, returning the same value as the libm '``sqrt``' 22408functions would, but without setting ``errno``. 22409 22410Arguments: 22411"""""""""" 22412 22413The first argument and the return type are floating-point numbers of the same 22414type. 22415 22416The second and third arguments specify the rounding mode and exception 22417behavior as described above. 22418 22419Semantics: 22420"""""""""" 22421 22422This function returns the nonnegative square root of the specified value. 22423If the value is less than negative zero, a floating-point exception occurs 22424and the return value is architecture specific. 22425 22426 22427'``llvm.experimental.constrained.pow``' Intrinsic 22428^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22429 22430Syntax: 22431""""""" 22432 22433:: 22434 22435 declare <type> 22436 @llvm.experimental.constrained.pow(<type> <op1>, <type> <op2>, 22437 metadata <rounding mode>, 22438 metadata <exception behavior>) 22439 22440Overview: 22441""""""""" 22442 22443The '``llvm.experimental.constrained.pow``' intrinsic returns the first operand 22444raised to the (positive or negative) power specified by the second operand. 22445 22446Arguments: 22447"""""""""" 22448 22449The first two arguments and the return value are floating-point numbers of the 22450same type. The second argument specifies the power to which the first argument 22451should be raised. 22452 22453The third and fourth arguments specify the rounding mode and exception 22454behavior as described above. 22455 22456Semantics: 22457"""""""""" 22458 22459This function returns the first value raised to the second power, 22460returning the same values as the libm ``pow`` functions would, and 22461handles error conditions in the same way. 22462 22463 22464'``llvm.experimental.constrained.powi``' Intrinsic 22465^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22466 22467Syntax: 22468""""""" 22469 22470:: 22471 22472 declare <type> 22473 @llvm.experimental.constrained.powi(<type> <op1>, i32 <op2>, 22474 metadata <rounding mode>, 22475 metadata <exception behavior>) 22476 22477Overview: 22478""""""""" 22479 22480The '``llvm.experimental.constrained.powi``' intrinsic returns the first operand 22481raised to the (positive or negative) power specified by the second operand. The 22482order of evaluation of multiplications is not defined. When a vector of 22483floating-point type is used, the second argument remains a scalar integer value. 22484 22485 22486Arguments: 22487"""""""""" 22488 22489The first argument and the return value are floating-point numbers of the same 22490type. The second argument is a 32-bit signed integer specifying the power to 22491which the first argument should be raised. 22492 22493The third and fourth arguments specify the rounding mode and exception 22494behavior as described above. 22495 22496Semantics: 22497"""""""""" 22498 22499This function returns the first value raised to the second power with an 22500unspecified sequence of rounding operations. 22501 22502 22503'``llvm.experimental.constrained.sin``' Intrinsic 22504^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22505 22506Syntax: 22507""""""" 22508 22509:: 22510 22511 declare <type> 22512 @llvm.experimental.constrained.sin(<type> <op1>, 22513 metadata <rounding mode>, 22514 metadata <exception behavior>) 22515 22516Overview: 22517""""""""" 22518 22519The '``llvm.experimental.constrained.sin``' intrinsic returns the sine of the 22520first operand. 22521 22522Arguments: 22523"""""""""" 22524 22525The first argument and the return type are floating-point numbers of the same 22526type. 22527 22528The second and third arguments specify the rounding mode and exception 22529behavior as described above. 22530 22531Semantics: 22532"""""""""" 22533 22534This function returns the sine of the specified operand, returning the 22535same values as the libm ``sin`` functions would, and handles error 22536conditions in the same way. 22537 22538 22539'``llvm.experimental.constrained.cos``' Intrinsic 22540^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22541 22542Syntax: 22543""""""" 22544 22545:: 22546 22547 declare <type> 22548 @llvm.experimental.constrained.cos(<type> <op1>, 22549 metadata <rounding mode>, 22550 metadata <exception behavior>) 22551 22552Overview: 22553""""""""" 22554 22555The '``llvm.experimental.constrained.cos``' intrinsic returns the cosine of the 22556first operand. 22557 22558Arguments: 22559"""""""""" 22560 22561The first argument and the return type are floating-point numbers of the same 22562type. 22563 22564The second and third arguments specify the rounding mode and exception 22565behavior as described above. 22566 22567Semantics: 22568"""""""""" 22569 22570This function returns the cosine of the specified operand, returning the 22571same values as the libm ``cos`` functions would, and handles error 22572conditions in the same way. 22573 22574 22575'``llvm.experimental.constrained.exp``' Intrinsic 22576^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22577 22578Syntax: 22579""""""" 22580 22581:: 22582 22583 declare <type> 22584 @llvm.experimental.constrained.exp(<type> <op1>, 22585 metadata <rounding mode>, 22586 metadata <exception behavior>) 22587 22588Overview: 22589""""""""" 22590 22591The '``llvm.experimental.constrained.exp``' intrinsic computes the base-e 22592exponential of the specified value. 22593 22594Arguments: 22595"""""""""" 22596 22597The first argument and the return value are floating-point numbers of the same 22598type. 22599 22600The second and third arguments specify the rounding mode and exception 22601behavior as described above. 22602 22603Semantics: 22604"""""""""" 22605 22606This function returns the same values as the libm ``exp`` functions 22607would, and handles error conditions in the same way. 22608 22609 22610'``llvm.experimental.constrained.exp2``' Intrinsic 22611^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22612 22613Syntax: 22614""""""" 22615 22616:: 22617 22618 declare <type> 22619 @llvm.experimental.constrained.exp2(<type> <op1>, 22620 metadata <rounding mode>, 22621 metadata <exception behavior>) 22622 22623Overview: 22624""""""""" 22625 22626The '``llvm.experimental.constrained.exp2``' intrinsic computes the base-2 22627exponential of the specified value. 22628 22629 22630Arguments: 22631"""""""""" 22632 22633The first argument and the return value are floating-point numbers of the same 22634type. 22635 22636The second and third arguments specify the rounding mode and exception 22637behavior as described above. 22638 22639Semantics: 22640"""""""""" 22641 22642This function returns the same values as the libm ``exp2`` functions 22643would, and handles error conditions in the same way. 22644 22645 22646'``llvm.experimental.constrained.log``' Intrinsic 22647^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22648 22649Syntax: 22650""""""" 22651 22652:: 22653 22654 declare <type> 22655 @llvm.experimental.constrained.log(<type> <op1>, 22656 metadata <rounding mode>, 22657 metadata <exception behavior>) 22658 22659Overview: 22660""""""""" 22661 22662The '``llvm.experimental.constrained.log``' intrinsic computes the base-e 22663logarithm of the specified value. 22664 22665Arguments: 22666"""""""""" 22667 22668The first argument and the return value are floating-point numbers of the same 22669type. 22670 22671The second and third arguments specify the rounding mode and exception 22672behavior as described above. 22673 22674 22675Semantics: 22676"""""""""" 22677 22678This function returns the same values as the libm ``log`` functions 22679would, and handles error conditions in the same way. 22680 22681 22682'``llvm.experimental.constrained.log10``' Intrinsic 22683^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22684 22685Syntax: 22686""""""" 22687 22688:: 22689 22690 declare <type> 22691 @llvm.experimental.constrained.log10(<type> <op1>, 22692 metadata <rounding mode>, 22693 metadata <exception behavior>) 22694 22695Overview: 22696""""""""" 22697 22698The '``llvm.experimental.constrained.log10``' intrinsic computes the base-10 22699logarithm of the specified value. 22700 22701Arguments: 22702"""""""""" 22703 22704The first argument and the return value are floating-point numbers of the same 22705type. 22706 22707The second and third arguments specify the rounding mode and exception 22708behavior as described above. 22709 22710Semantics: 22711"""""""""" 22712 22713This function returns the same values as the libm ``log10`` functions 22714would, and handles error conditions in the same way. 22715 22716 22717'``llvm.experimental.constrained.log2``' Intrinsic 22718^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22719 22720Syntax: 22721""""""" 22722 22723:: 22724 22725 declare <type> 22726 @llvm.experimental.constrained.log2(<type> <op1>, 22727 metadata <rounding mode>, 22728 metadata <exception behavior>) 22729 22730Overview: 22731""""""""" 22732 22733The '``llvm.experimental.constrained.log2``' intrinsic computes the base-2 22734logarithm of the specified value. 22735 22736Arguments: 22737"""""""""" 22738 22739The first argument and the return value are floating-point numbers of the same 22740type. 22741 22742The second and third arguments specify the rounding mode and exception 22743behavior as described above. 22744 22745Semantics: 22746"""""""""" 22747 22748This function returns the same values as the libm ``log2`` functions 22749would, and handles error conditions in the same way. 22750 22751 22752'``llvm.experimental.constrained.rint``' Intrinsic 22753^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22754 22755Syntax: 22756""""""" 22757 22758:: 22759 22760 declare <type> 22761 @llvm.experimental.constrained.rint(<type> <op1>, 22762 metadata <rounding mode>, 22763 metadata <exception behavior>) 22764 22765Overview: 22766""""""""" 22767 22768The '``llvm.experimental.constrained.rint``' intrinsic returns the first 22769operand rounded to the nearest integer. It may raise an inexact floating-point 22770exception if the operand is not an integer. 22771 22772Arguments: 22773"""""""""" 22774 22775The first argument and the return value are floating-point numbers of the same 22776type. 22777 22778The second and third arguments specify the rounding mode and exception 22779behavior as described above. 22780 22781Semantics: 22782"""""""""" 22783 22784This function returns the same values as the libm ``rint`` functions 22785would, and handles error conditions in the same way. The rounding mode is 22786described, not determined, by the rounding mode argument. The actual rounding 22787mode is determined by the runtime floating-point environment. The rounding 22788mode argument is only intended as information to the compiler. 22789 22790 22791'``llvm.experimental.constrained.lrint``' Intrinsic 22792^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22793 22794Syntax: 22795""""""" 22796 22797:: 22798 22799 declare <inttype> 22800 @llvm.experimental.constrained.lrint(<fptype> <op1>, 22801 metadata <rounding mode>, 22802 metadata <exception behavior>) 22803 22804Overview: 22805""""""""" 22806 22807The '``llvm.experimental.constrained.lrint``' intrinsic returns the first 22808operand rounded to the nearest integer. An inexact floating-point exception 22809will be raised if the operand is not an integer. An invalid exception is 22810raised if the result is too large to fit into a supported integer type, 22811and in this case the result is undefined. 22812 22813Arguments: 22814"""""""""" 22815 22816The first argument is a floating-point number. The return value is an 22817integer type. Not all types are supported on all targets. The supported 22818types are the same as the ``llvm.lrint`` intrinsic and the ``lrint`` 22819libm functions. 22820 22821The second and third arguments specify the rounding mode and exception 22822behavior as described above. 22823 22824Semantics: 22825"""""""""" 22826 22827This function returns the same values as the libm ``lrint`` functions 22828would, and handles error conditions in the same way. 22829 22830The rounding mode is described, not determined, by the rounding mode 22831argument. The actual rounding mode is determined by the runtime floating-point 22832environment. The rounding mode argument is only intended as information 22833to the compiler. 22834 22835If the runtime floating-point environment is using the default rounding mode 22836then the results will be the same as the llvm.lrint intrinsic. 22837 22838 22839'``llvm.experimental.constrained.llrint``' Intrinsic 22840^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22841 22842Syntax: 22843""""""" 22844 22845:: 22846 22847 declare <inttype> 22848 @llvm.experimental.constrained.llrint(<fptype> <op1>, 22849 metadata <rounding mode>, 22850 metadata <exception behavior>) 22851 22852Overview: 22853""""""""" 22854 22855The '``llvm.experimental.constrained.llrint``' intrinsic returns the first 22856operand rounded to the nearest integer. An inexact floating-point exception 22857will be raised if the operand is not an integer. An invalid exception is 22858raised if the result is too large to fit into a supported integer type, 22859and in this case the result is undefined. 22860 22861Arguments: 22862"""""""""" 22863 22864The first argument is a floating-point number. The return value is an 22865integer type. Not all types are supported on all targets. The supported 22866types are the same as the ``llvm.llrint`` intrinsic and the ``llrint`` 22867libm functions. 22868 22869The second and third arguments specify the rounding mode and exception 22870behavior as described above. 22871 22872Semantics: 22873"""""""""" 22874 22875This function returns the same values as the libm ``llrint`` functions 22876would, and handles error conditions in the same way. 22877 22878The rounding mode is described, not determined, by the rounding mode 22879argument. The actual rounding mode is determined by the runtime floating-point 22880environment. The rounding mode argument is only intended as information 22881to the compiler. 22882 22883If the runtime floating-point environment is using the default rounding mode 22884then the results will be the same as the llvm.llrint intrinsic. 22885 22886 22887'``llvm.experimental.constrained.nearbyint``' Intrinsic 22888^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22889 22890Syntax: 22891""""""" 22892 22893:: 22894 22895 declare <type> 22896 @llvm.experimental.constrained.nearbyint(<type> <op1>, 22897 metadata <rounding mode>, 22898 metadata <exception behavior>) 22899 22900Overview: 22901""""""""" 22902 22903The '``llvm.experimental.constrained.nearbyint``' intrinsic returns the first 22904operand rounded to the nearest integer. It will not raise an inexact 22905floating-point exception if the operand is not an integer. 22906 22907 22908Arguments: 22909"""""""""" 22910 22911The first argument and the return value are floating-point numbers of the same 22912type. 22913 22914The second and third arguments specify the rounding mode and exception 22915behavior as described above. 22916 22917Semantics: 22918"""""""""" 22919 22920This function returns the same values as the libm ``nearbyint`` functions 22921would, and handles error conditions in the same way. The rounding mode is 22922described, not determined, by the rounding mode argument. The actual rounding 22923mode is determined by the runtime floating-point environment. The rounding 22924mode argument is only intended as information to the compiler. 22925 22926 22927'``llvm.experimental.constrained.maxnum``' Intrinsic 22928^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22929 22930Syntax: 22931""""""" 22932 22933:: 22934 22935 declare <type> 22936 @llvm.experimental.constrained.maxnum(<type> <op1>, <type> <op2> 22937 metadata <exception behavior>) 22938 22939Overview: 22940""""""""" 22941 22942The '``llvm.experimental.constrained.maxnum``' intrinsic returns the maximum 22943of the two arguments. 22944 22945Arguments: 22946"""""""""" 22947 22948The first two arguments and the return value are floating-point numbers 22949of the same type. 22950 22951The third argument specifies the exception behavior as described above. 22952 22953Semantics: 22954"""""""""" 22955 22956This function follows the IEEE-754 semantics for maxNum. 22957 22958 22959'``llvm.experimental.constrained.minnum``' Intrinsic 22960^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22961 22962Syntax: 22963""""""" 22964 22965:: 22966 22967 declare <type> 22968 @llvm.experimental.constrained.minnum(<type> <op1>, <type> <op2> 22969 metadata <exception behavior>) 22970 22971Overview: 22972""""""""" 22973 22974The '``llvm.experimental.constrained.minnum``' intrinsic returns the minimum 22975of the two arguments. 22976 22977Arguments: 22978"""""""""" 22979 22980The first two arguments and the return value are floating-point numbers 22981of the same type. 22982 22983The third argument specifies the exception behavior as described above. 22984 22985Semantics: 22986"""""""""" 22987 22988This function follows the IEEE-754 semantics for minNum. 22989 22990 22991'``llvm.experimental.constrained.maximum``' Intrinsic 22992^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 22993 22994Syntax: 22995""""""" 22996 22997:: 22998 22999 declare <type> 23000 @llvm.experimental.constrained.maximum(<type> <op1>, <type> <op2> 23001 metadata <exception behavior>) 23002 23003Overview: 23004""""""""" 23005 23006The '``llvm.experimental.constrained.maximum``' intrinsic returns the maximum 23007of the two arguments, propagating NaNs and treating -0.0 as less than +0.0. 23008 23009Arguments: 23010"""""""""" 23011 23012The first two arguments and the return value are floating-point numbers 23013of the same type. 23014 23015The third argument specifies the exception behavior as described above. 23016 23017Semantics: 23018"""""""""" 23019 23020This function follows semantics specified in the draft of IEEE 754-2018. 23021 23022 23023'``llvm.experimental.constrained.minimum``' Intrinsic 23024^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23025 23026Syntax: 23027""""""" 23028 23029:: 23030 23031 declare <type> 23032 @llvm.experimental.constrained.minimum(<type> <op1>, <type> <op2> 23033 metadata <exception behavior>) 23034 23035Overview: 23036""""""""" 23037 23038The '``llvm.experimental.constrained.minimum``' intrinsic returns the minimum 23039of the two arguments, propagating NaNs and treating -0.0 as less than +0.0. 23040 23041Arguments: 23042"""""""""" 23043 23044The first two arguments and the return value are floating-point numbers 23045of the same type. 23046 23047The third argument specifies the exception behavior as described above. 23048 23049Semantics: 23050"""""""""" 23051 23052This function follows semantics specified in the draft of IEEE 754-2018. 23053 23054 23055'``llvm.experimental.constrained.ceil``' Intrinsic 23056^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23057 23058Syntax: 23059""""""" 23060 23061:: 23062 23063 declare <type> 23064 @llvm.experimental.constrained.ceil(<type> <op1>, 23065 metadata <exception behavior>) 23066 23067Overview: 23068""""""""" 23069 23070The '``llvm.experimental.constrained.ceil``' intrinsic returns the ceiling of the 23071first operand. 23072 23073Arguments: 23074"""""""""" 23075 23076The first argument and the return value are floating-point numbers of the same 23077type. 23078 23079The second argument specifies the exception behavior as described above. 23080 23081Semantics: 23082"""""""""" 23083 23084This function returns the same values as the libm ``ceil`` functions 23085would and handles error conditions in the same way. 23086 23087 23088'``llvm.experimental.constrained.floor``' Intrinsic 23089^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23090 23091Syntax: 23092""""""" 23093 23094:: 23095 23096 declare <type> 23097 @llvm.experimental.constrained.floor(<type> <op1>, 23098 metadata <exception behavior>) 23099 23100Overview: 23101""""""""" 23102 23103The '``llvm.experimental.constrained.floor``' intrinsic returns the floor of the 23104first operand. 23105 23106Arguments: 23107"""""""""" 23108 23109The first argument and the return value are floating-point numbers of the same 23110type. 23111 23112The second argument specifies the exception behavior as described above. 23113 23114Semantics: 23115"""""""""" 23116 23117This function returns the same values as the libm ``floor`` functions 23118would and handles error conditions in the same way. 23119 23120 23121'``llvm.experimental.constrained.round``' Intrinsic 23122^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23123 23124Syntax: 23125""""""" 23126 23127:: 23128 23129 declare <type> 23130 @llvm.experimental.constrained.round(<type> <op1>, 23131 metadata <exception behavior>) 23132 23133Overview: 23134""""""""" 23135 23136The '``llvm.experimental.constrained.round``' intrinsic returns the first 23137operand rounded to the nearest integer. 23138 23139Arguments: 23140"""""""""" 23141 23142The first argument and the return value are floating-point numbers of the same 23143type. 23144 23145The second argument specifies the exception behavior as described above. 23146 23147Semantics: 23148"""""""""" 23149 23150This function returns the same values as the libm ``round`` functions 23151would and handles error conditions in the same way. 23152 23153 23154'``llvm.experimental.constrained.roundeven``' Intrinsic 23155^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23156 23157Syntax: 23158""""""" 23159 23160:: 23161 23162 declare <type> 23163 @llvm.experimental.constrained.roundeven(<type> <op1>, 23164 metadata <exception behavior>) 23165 23166Overview: 23167""""""""" 23168 23169The '``llvm.experimental.constrained.roundeven``' intrinsic returns the first 23170operand rounded to the nearest integer in floating-point format, rounding 23171halfway cases to even (that is, to the nearest value that is an even integer), 23172regardless of the current rounding direction. 23173 23174Arguments: 23175"""""""""" 23176 23177The first argument and the return value are floating-point numbers of the same 23178type. 23179 23180The second argument specifies the exception behavior as described above. 23181 23182Semantics: 23183"""""""""" 23184 23185This function implements IEEE-754 operation ``roundToIntegralTiesToEven``. It 23186also behaves in the same way as C standard function ``roundeven`` and can signal 23187the invalid operation exception for a SNAN operand. 23188 23189 23190'``llvm.experimental.constrained.lround``' Intrinsic 23191^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23192 23193Syntax: 23194""""""" 23195 23196:: 23197 23198 declare <inttype> 23199 @llvm.experimental.constrained.lround(<fptype> <op1>, 23200 metadata <exception behavior>) 23201 23202Overview: 23203""""""""" 23204 23205The '``llvm.experimental.constrained.lround``' intrinsic returns the first 23206operand rounded to the nearest integer with ties away from zero. It will 23207raise an inexact floating-point exception if the operand is not an integer. 23208An invalid exception is raised if the result is too large to fit into a 23209supported integer type, and in this case the result is undefined. 23210 23211Arguments: 23212"""""""""" 23213 23214The first argument is a floating-point number. The return value is an 23215integer type. Not all types are supported on all targets. The supported 23216types are the same as the ``llvm.lround`` intrinsic and the ``lround`` 23217libm functions. 23218 23219The second argument specifies the exception behavior as described above. 23220 23221Semantics: 23222"""""""""" 23223 23224This function returns the same values as the libm ``lround`` functions 23225would and handles error conditions in the same way. 23226 23227 23228'``llvm.experimental.constrained.llround``' Intrinsic 23229^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23230 23231Syntax: 23232""""""" 23233 23234:: 23235 23236 declare <inttype> 23237 @llvm.experimental.constrained.llround(<fptype> <op1>, 23238 metadata <exception behavior>) 23239 23240Overview: 23241""""""""" 23242 23243The '``llvm.experimental.constrained.llround``' intrinsic returns the first 23244operand rounded to the nearest integer with ties away from zero. It will 23245raise an inexact floating-point exception if the operand is not an integer. 23246An invalid exception is raised if the result is too large to fit into a 23247supported integer type, and in this case the result is undefined. 23248 23249Arguments: 23250"""""""""" 23251 23252The first argument is a floating-point number. The return value is an 23253integer type. Not all types are supported on all targets. The supported 23254types are the same as the ``llvm.llround`` intrinsic and the ``llround`` 23255libm functions. 23256 23257The second argument specifies the exception behavior as described above. 23258 23259Semantics: 23260"""""""""" 23261 23262This function returns the same values as the libm ``llround`` functions 23263would and handles error conditions in the same way. 23264 23265 23266'``llvm.experimental.constrained.trunc``' Intrinsic 23267^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23268 23269Syntax: 23270""""""" 23271 23272:: 23273 23274 declare <type> 23275 @llvm.experimental.constrained.trunc(<type> <op1>, 23276 metadata <exception behavior>) 23277 23278Overview: 23279""""""""" 23280 23281The '``llvm.experimental.constrained.trunc``' intrinsic returns the first 23282operand rounded to the nearest integer not larger in magnitude than the 23283operand. 23284 23285Arguments: 23286"""""""""" 23287 23288The first argument and the return value are floating-point numbers of the same 23289type. 23290 23291The second argument specifies the exception behavior as described above. 23292 23293Semantics: 23294"""""""""" 23295 23296This function returns the same values as the libm ``trunc`` functions 23297would and handles error conditions in the same way. 23298 23299.. _int_experimental_noalias_scope_decl: 23300 23301'``llvm.experimental.noalias.scope.decl``' Intrinsic 23302^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23303 23304Syntax: 23305""""""" 23306 23307 23308:: 23309 23310 declare void @llvm.experimental.noalias.scope.decl(metadata !id.scope.list) 23311 23312Overview: 23313""""""""" 23314 23315The ``llvm.experimental.noalias.scope.decl`` intrinsic identifies where a 23316noalias scope is declared. When the intrinsic is duplicated, a decision must 23317also be made about the scope: depending on the reason of the duplication, 23318the scope might need to be duplicated as well. 23319 23320 23321Arguments: 23322"""""""""" 23323 23324The ``!id.scope.list`` argument is metadata that is a list of ``noalias`` 23325metadata references. The format is identical to that required for ``noalias`` 23326metadata. This list must have exactly one element. 23327 23328Semantics: 23329"""""""""" 23330 23331The ``llvm.experimental.noalias.scope.decl`` intrinsic identifies where a 23332noalias scope is declared. When the intrinsic is duplicated, a decision must 23333also be made about the scope: depending on the reason of the duplication, 23334the scope might need to be duplicated as well. 23335 23336For example, when the intrinsic is used inside a loop body, and that loop is 23337unrolled, the associated noalias scope must also be duplicated. Otherwise, the 23338noalias property it signifies would spill across loop iterations, whereas it 23339was only valid within a single iteration. 23340 23341.. code-block:: llvm 23342 23343 ; This examples shows two possible positions for noalias.decl and how they impact the semantics: 23344 ; If it is outside the loop (Version 1), then %a and %b are noalias across *all* iterations. 23345 ; If it is inside the loop (Version 2), then %a and %b are noalias only within *one* iteration. 23346 declare void @decl_in_loop(ptr %a.base, ptr %b.base) { 23347 entry: 23348 ; call void @llvm.experimental.noalias.scope.decl(metadata !2) ; Version 1: noalias decl outside loop 23349 br label %loop 23350 23351 loop: 23352 %a = phi ptr [ %a.base, %entry ], [ %a.inc, %loop ] 23353 %b = phi ptr [ %b.base, %entry ], [ %b.inc, %loop ] 23354 ; call void @llvm.experimental.noalias.scope.decl(metadata !2) ; Version 2: noalias decl inside loop 23355 %val = load i8, ptr %a, !alias.scope !2 23356 store i8 %val, ptr %b, !noalias !2 23357 %a.inc = getelementptr inbounds i8, ptr %a, i64 1 23358 %b.inc = getelementptr inbounds i8, ptr %b, i64 1 23359 %cond = call i1 @cond() 23360 br i1 %cond, label %loop, label %exit 23361 23362 exit: 23363 ret void 23364 } 23365 23366 !0 = !{!0} ; domain 23367 !1 = !{!1, !0} ; scope 23368 !2 = !{!1} ; scope list 23369 23370Multiple calls to `@llvm.experimental.noalias.scope.decl` for the same scope 23371are possible, but one should never dominate another. Violations are pointed out 23372by the verifier as they indicate a problem in either a transformation pass or 23373the input. 23374 23375 23376Floating Point Environment Manipulation intrinsics 23377-------------------------------------------------- 23378 23379These functions read or write floating point environment, such as rounding 23380mode or state of floating point exceptions. Altering the floating point 23381environment requires special care. See :ref:`Floating Point Environment <floatenv>`. 23382 23383'``llvm.flt.rounds``' Intrinsic 23384^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23385 23386Syntax: 23387""""""" 23388 23389:: 23390 23391 declare i32 @llvm.flt.rounds() 23392 23393Overview: 23394""""""""" 23395 23396The '``llvm.flt.rounds``' intrinsic reads the current rounding mode. 23397 23398Semantics: 23399"""""""""" 23400 23401The '``llvm.flt.rounds``' intrinsic returns the current rounding mode. 23402Encoding of the returned values is same as the result of ``FLT_ROUNDS``, 23403specified by C standard: 23404 23405:: 23406 23407 0 - toward zero 23408 1 - to nearest, ties to even 23409 2 - toward positive infinity 23410 3 - toward negative infinity 23411 4 - to nearest, ties away from zero 23412 23413Other values may be used to represent additional rounding modes, supported by a 23414target. These values are target-specific. 23415 23416 23417'``llvm.set.rounding``' Intrinsic 23418^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23419 23420Syntax: 23421""""""" 23422 23423:: 23424 23425 declare void @llvm.set.rounding(i32 <val>) 23426 23427Overview: 23428""""""""" 23429 23430The '``llvm.set.rounding``' intrinsic sets current rounding mode. 23431 23432Arguments: 23433"""""""""" 23434 23435The argument is the required rounding mode. Encoding of rounding mode is 23436the same as used by '``llvm.flt.rounds``'. 23437 23438Semantics: 23439"""""""""" 23440 23441The '``llvm.set.rounding``' intrinsic sets the current rounding mode. It is 23442similar to C library function 'fesetround', however this intrinsic does not 23443return any value and uses platform-independent representation of IEEE rounding 23444modes. 23445 23446 23447Floating-Point Test Intrinsics 23448------------------------------ 23449 23450These functions get properties of floating-point values. 23451 23452 23453'``llvm.is.fpclass``' Intrinsic 23454^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23455 23456Syntax: 23457""""""" 23458 23459:: 23460 23461 declare i1 @llvm.is.fpclass(<fptype> <op>, i32 <test>) 23462 declare <N x i1> @llvm.is.fpclass(<vector-fptype> <op>, i32 <test>) 23463 23464Overview: 23465""""""""" 23466 23467The '``llvm.is.fpclass``' intrinsic returns a boolean value or vector of boolean 23468values depending on whether the first argument satisfies the test specified by 23469the second argument. 23470 23471If the first argument is a floating-point scalar, then the result type is a 23472boolean (:ref:`i1 <t_integer>`). 23473 23474If the first argument is a floating-point vector, then the result type is a 23475vector of boolean with the same number of elements as the first argument. 23476 23477Arguments: 23478"""""""""" 23479 23480The first argument to the '``llvm.is.fpclass``' intrinsic must be 23481:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` 23482of floating-point values. 23483 23484The second argument specifies, which tests to perform. It must be a compile-time 23485integer constant, each bit in which specifies floating-point class: 23486 23487+-------+----------------------+ 23488| Bit # | floating-point class | 23489+=======+======================+ 23490| 0 | Signaling NaN | 23491+-------+----------------------+ 23492| 1 | Quiet NaN | 23493+-------+----------------------+ 23494| 2 | Negative infinity | 23495+-------+----------------------+ 23496| 3 | Negative normal | 23497+-------+----------------------+ 23498| 4 | Negative subnormal | 23499+-------+----------------------+ 23500| 5 | Negative zero | 23501+-------+----------------------+ 23502| 6 | Positive zero | 23503+-------+----------------------+ 23504| 7 | Positive subnormal | 23505+-------+----------------------+ 23506| 8 | Positive normal | 23507+-------+----------------------+ 23508| 9 | Positive infinity | 23509+-------+----------------------+ 23510 23511Semantics: 23512"""""""""" 23513 23514The function checks if ``op`` belongs to any of the floating-point classes 23515specified by ``test``. If ``op`` is a vector, then the check is made element by 23516element. Each check yields an :ref:`i1 <t_integer>` result, which is ``true``, 23517if the element value satisfies the specified test. The argument ``test`` is a 23518bit mask where each bit specifies floating-point class to test. For example, the 23519value 0x108 makes test for normal value, - bits 3 and 8 in it are set, which 23520means that the function returns ``true`` if ``op`` is a positive or negative 23521normal value. The function never raises floating-point exceptions. 23522 23523 23524General Intrinsics 23525------------------ 23526 23527This class of intrinsics is designed to be generic and has no specific 23528purpose. 23529 23530'``llvm.var.annotation``' Intrinsic 23531^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23532 23533Syntax: 23534""""""" 23535 23536:: 23537 23538 declare void @llvm.var.annotation(ptr <val>, ptr <str>, ptr <str>, i32 <int>) 23539 23540Overview: 23541""""""""" 23542 23543The '``llvm.var.annotation``' intrinsic. 23544 23545Arguments: 23546"""""""""" 23547 23548The first argument is a pointer to a value, the second is a pointer to a 23549global string, the third is a pointer to a global string which is the 23550source file name, and the last argument is the line number. 23551 23552Semantics: 23553"""""""""" 23554 23555This intrinsic allows annotation of local variables with arbitrary 23556strings. This can be useful for special purpose optimizations that want 23557to look for these annotations. These have no other defined use; they are 23558ignored by code generation and optimization. 23559 23560'``llvm.ptr.annotation.*``' Intrinsic 23561^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23562 23563Syntax: 23564""""""" 23565 23566This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a 23567pointer to an integer of any width. *NOTE* you must specify an address space for 23568the pointer. The identifier for the default address space is the integer 23569'``0``'. 23570 23571:: 23572 23573 declare ptr @llvm.ptr.annotation.p0(ptr <val>, ptr <str>, ptr <str>, i32 <int>) 23574 declare ptr @llvm.ptr.annotation.p1(ptr addrspace(1) <val>, ptr <str>, ptr <str>, i32 <int>) 23575 23576Overview: 23577""""""""" 23578 23579The '``llvm.ptr.annotation``' intrinsic. 23580 23581Arguments: 23582"""""""""" 23583 23584The first argument is a pointer to an integer value of arbitrary bitwidth 23585(result of some expression), the second is a pointer to a global string, the 23586third is a pointer to a global string which is the source file name, and the 23587last argument is the line number. It returns the value of the first argument. 23588 23589Semantics: 23590"""""""""" 23591 23592This intrinsic allows annotation of a pointer to an integer with arbitrary 23593strings. This can be useful for special purpose optimizations that want to look 23594for these annotations. These have no other defined use; transformations preserve 23595annotations on a best-effort basis but are allowed to replace the intrinsic with 23596its first argument without breaking semantics and the intrinsic is completely 23597dropped during instruction selection. 23598 23599'``llvm.annotation.*``' Intrinsic 23600^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23601 23602Syntax: 23603""""""" 23604 23605This is an overloaded intrinsic. You can use '``llvm.annotation``' on 23606any integer bit width. 23607 23608:: 23609 23610 declare i8 @llvm.annotation.i8(i8 <val>, ptr <str>, ptr <str>, i32 <int>) 23611 declare i16 @llvm.annotation.i16(i16 <val>, ptr <str>, ptr <str>, i32 <int>) 23612 declare i32 @llvm.annotation.i32(i32 <val>, ptr <str>, ptr <str>, i32 <int>) 23613 declare i64 @llvm.annotation.i64(i64 <val>, ptr <str>, ptr <str>, i32 <int>) 23614 declare i256 @llvm.annotation.i256(i256 <val>, ptr <str>, ptr <str>, i32 <int>) 23615 23616Overview: 23617""""""""" 23618 23619The '``llvm.annotation``' intrinsic. 23620 23621Arguments: 23622"""""""""" 23623 23624The first argument is an integer value (result of some expression), the 23625second is a pointer to a global string, the third is a pointer to a 23626global string which is the source file name, and the last argument is 23627the line number. It returns the value of the first argument. 23628 23629Semantics: 23630"""""""""" 23631 23632This intrinsic allows annotations to be put on arbitrary expressions with 23633arbitrary strings. This can be useful for special purpose optimizations that 23634want to look for these annotations. These have no other defined use; 23635transformations preserve annotations on a best-effort basis but are allowed to 23636replace the intrinsic with its first argument without breaking semantics and the 23637intrinsic is completely dropped during instruction selection. 23638 23639'``llvm.codeview.annotation``' Intrinsic 23640^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23641 23642Syntax: 23643""""""" 23644 23645This annotation emits a label at its program point and an associated 23646``S_ANNOTATION`` codeview record with some additional string metadata. This is 23647used to implement MSVC's ``__annotation`` intrinsic. It is marked 23648``noduplicate``, so calls to this intrinsic prevent inlining and should be 23649considered expensive. 23650 23651:: 23652 23653 declare void @llvm.codeview.annotation(metadata) 23654 23655Arguments: 23656"""""""""" 23657 23658The argument should be an MDTuple containing any number of MDStrings. 23659 23660'``llvm.trap``' Intrinsic 23661^^^^^^^^^^^^^^^^^^^^^^^^^ 23662 23663Syntax: 23664""""""" 23665 23666:: 23667 23668 declare void @llvm.trap() cold noreturn nounwind 23669 23670Overview: 23671""""""""" 23672 23673The '``llvm.trap``' intrinsic. 23674 23675Arguments: 23676"""""""""" 23677 23678None. 23679 23680Semantics: 23681"""""""""" 23682 23683This intrinsic is lowered to the target dependent trap instruction. If 23684the target does not have a trap instruction, this intrinsic will be 23685lowered to a call of the ``abort()`` function. 23686 23687'``llvm.debugtrap``' Intrinsic 23688^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23689 23690Syntax: 23691""""""" 23692 23693:: 23694 23695 declare void @llvm.debugtrap() nounwind 23696 23697Overview: 23698""""""""" 23699 23700The '``llvm.debugtrap``' intrinsic. 23701 23702Arguments: 23703"""""""""" 23704 23705None. 23706 23707Semantics: 23708"""""""""" 23709 23710This intrinsic is lowered to code which is intended to cause an 23711execution trap with the intention of requesting the attention of a 23712debugger. 23713 23714'``llvm.ubsantrap``' Intrinsic 23715^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23716 23717Syntax: 23718""""""" 23719 23720:: 23721 23722 declare void @llvm.ubsantrap(i8 immarg) cold noreturn nounwind 23723 23724Overview: 23725""""""""" 23726 23727The '``llvm.ubsantrap``' intrinsic. 23728 23729Arguments: 23730"""""""""" 23731 23732An integer describing the kind of failure detected. 23733 23734Semantics: 23735"""""""""" 23736 23737This intrinsic is lowered to code which is intended to cause an execution trap, 23738embedding the argument into encoding of that trap somehow to discriminate 23739crashes if possible. 23740 23741Equivalent to ``@llvm.trap`` for targets that do not support this behaviour. 23742 23743'``llvm.stackprotector``' Intrinsic 23744^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23745 23746Syntax: 23747""""""" 23748 23749:: 23750 23751 declare void @llvm.stackprotector(ptr <guard>, ptr <slot>) 23752 23753Overview: 23754""""""""" 23755 23756The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it 23757onto the stack at ``slot``. The stack slot is adjusted to ensure that it 23758is placed on the stack before local variables. 23759 23760Arguments: 23761"""""""""" 23762 23763The ``llvm.stackprotector`` intrinsic requires two pointer arguments. 23764The first argument is the value loaded from the stack guard 23765``@__stack_chk_guard``. The second variable is an ``alloca`` that has 23766enough space to hold the value of the guard. 23767 23768Semantics: 23769"""""""""" 23770 23771This intrinsic causes the prologue/epilogue inserter to force the position of 23772the ``AllocaInst`` stack slot to be before local variables on the stack. This is 23773to ensure that if a local variable on the stack is overwritten, it will destroy 23774the value of the guard. When the function exits, the guard on the stack is 23775checked against the original guard by ``llvm.stackprotectorcheck``. If they are 23776different, then ``llvm.stackprotectorcheck`` causes the program to abort by 23777calling the ``__stack_chk_fail()`` function. 23778 23779'``llvm.stackguard``' Intrinsic 23780^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23781 23782Syntax: 23783""""""" 23784 23785:: 23786 23787 declare ptr @llvm.stackguard() 23788 23789Overview: 23790""""""""" 23791 23792The ``llvm.stackguard`` intrinsic returns the system stack guard value. 23793 23794It should not be generated by frontends, since it is only for internal usage. 23795The reason why we create this intrinsic is that we still support IR form Stack 23796Protector in FastISel. 23797 23798Arguments: 23799"""""""""" 23800 23801None. 23802 23803Semantics: 23804"""""""""" 23805 23806On some platforms, the value returned by this intrinsic remains unchanged 23807between loads in the same thread. On other platforms, it returns the same 23808global variable value, if any, e.g. ``@__stack_chk_guard``. 23809 23810Currently some platforms have IR-level customized stack guard loading (e.g. 23811X86 Linux) that is not handled by ``llvm.stackguard()``, while they should be 23812in the future. 23813 23814'``llvm.objectsize``' Intrinsic 23815^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23816 23817Syntax: 23818""""""" 23819 23820:: 23821 23822 declare i32 @llvm.objectsize.i32(ptr <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>) 23823 declare i64 @llvm.objectsize.i64(ptr <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>) 23824 23825Overview: 23826""""""""" 23827 23828The ``llvm.objectsize`` intrinsic is designed to provide information to the 23829optimizer to determine whether a) an operation (like memcpy) will overflow a 23830buffer that corresponds to an object, or b) that a runtime check for overflow 23831isn't necessary. An object in this context means an allocation of a specific 23832class, structure, array, or other object. 23833 23834Arguments: 23835"""""""""" 23836 23837The ``llvm.objectsize`` intrinsic takes four arguments. The first argument is a 23838pointer to or into the ``object``. The second argument determines whether 23839``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size is 23840unknown. The third argument controls how ``llvm.objectsize`` acts when ``null`` 23841in address space 0 is used as its pointer argument. If it's ``false``, 23842``llvm.objectsize`` reports 0 bytes available when given ``null``. Otherwise, if 23843the ``null`` is in a non-zero address space or if ``true`` is given for the 23844third argument of ``llvm.objectsize``, we assume its size is unknown. The fourth 23845argument to ``llvm.objectsize`` determines if the value should be evaluated at 23846runtime. 23847 23848The second, third, and fourth arguments only accept constants. 23849 23850Semantics: 23851"""""""""" 23852 23853The ``llvm.objectsize`` intrinsic is lowered to a value representing the size of 23854the object concerned. If the size cannot be determined, ``llvm.objectsize`` 23855returns ``i32/i64 -1 or 0`` (depending on the ``min`` argument). 23856 23857'``llvm.expect``' Intrinsic 23858^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23859 23860Syntax: 23861""""""" 23862 23863This is an overloaded intrinsic. You can use ``llvm.expect`` on any 23864integer bit width. 23865 23866:: 23867 23868 declare i1 @llvm.expect.i1(i1 <val>, i1 <expected_val>) 23869 declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>) 23870 declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>) 23871 23872Overview: 23873""""""""" 23874 23875The ``llvm.expect`` intrinsic provides information about expected (the 23876most probable) value of ``val``, which can be used by optimizers. 23877 23878Arguments: 23879"""""""""" 23880 23881The ``llvm.expect`` intrinsic takes two arguments. The first argument is 23882a value. The second argument is an expected value. 23883 23884Semantics: 23885"""""""""" 23886 23887This intrinsic is lowered to the ``val``. 23888 23889'``llvm.expect.with.probability``' Intrinsic 23890^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23891 23892Syntax: 23893""""""" 23894 23895This intrinsic is similar to ``llvm.expect``. This is an overloaded intrinsic. 23896You can use ``llvm.expect.with.probability`` on any integer bit width. 23897 23898:: 23899 23900 declare i1 @llvm.expect.with.probability.i1(i1 <val>, i1 <expected_val>, double <prob>) 23901 declare i32 @llvm.expect.with.probability.i32(i32 <val>, i32 <expected_val>, double <prob>) 23902 declare i64 @llvm.expect.with.probability.i64(i64 <val>, i64 <expected_val>, double <prob>) 23903 23904Overview: 23905""""""""" 23906 23907The ``llvm.expect.with.probability`` intrinsic provides information about 23908expected value of ``val`` with probability(or confidence) ``prob``, which can 23909be used by optimizers. 23910 23911Arguments: 23912"""""""""" 23913 23914The ``llvm.expect.with.probability`` intrinsic takes three arguments. The first 23915argument is a value. The second argument is an expected value. The third 23916argument is a probability. 23917 23918Semantics: 23919"""""""""" 23920 23921This intrinsic is lowered to the ``val``. 23922 23923.. _int_assume: 23924 23925'``llvm.assume``' Intrinsic 23926^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23927 23928Syntax: 23929""""""" 23930 23931:: 23932 23933 declare void @llvm.assume(i1 %cond) 23934 23935Overview: 23936""""""""" 23937 23938The ``llvm.assume`` allows the optimizer to assume that the provided 23939condition is true. This information can then be used in simplifying other parts 23940of the code. 23941 23942More complex assumptions can be encoded as 23943:ref:`assume operand bundles <assume_opbundles>`. 23944 23945Arguments: 23946"""""""""" 23947 23948The argument of the call is the condition which the optimizer may assume is 23949always true. 23950 23951Semantics: 23952"""""""""" 23953 23954The intrinsic allows the optimizer to assume that the provided condition is 23955always true whenever the control flow reaches the intrinsic call. No code is 23956generated for this intrinsic, and instructions that contribute only to the 23957provided condition are not used for code generation. If the condition is 23958violated during execution, the behavior is undefined. 23959 23960Note that the optimizer might limit the transformations performed on values 23961used by the ``llvm.assume`` intrinsic in order to preserve the instructions 23962only used to form the intrinsic's input argument. This might prove undesirable 23963if the extra information provided by the ``llvm.assume`` intrinsic does not cause 23964sufficient overall improvement in code quality. For this reason, 23965``llvm.assume`` should not be used to document basic mathematical invariants 23966that the optimizer can otherwise deduce or facts that are of little use to the 23967optimizer. 23968 23969.. _int_ssa_copy: 23970 23971'``llvm.ssa.copy``' Intrinsic 23972^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23973 23974Syntax: 23975""""""" 23976 23977:: 23978 23979 declare type @llvm.ssa.copy(type %operand) returned(1) readnone 23980 23981Arguments: 23982"""""""""" 23983 23984The first argument is an operand which is used as the returned value. 23985 23986Overview: 23987"""""""""" 23988 23989The ``llvm.ssa.copy`` intrinsic can be used to attach information to 23990operations by copying them and giving them new names. For example, 23991the PredicateInfo utility uses it to build Extended SSA form, and 23992attach various forms of information to operands that dominate specific 23993uses. It is not meant for general use, only for building temporary 23994renaming forms that require value splits at certain points. 23995 23996.. _type.test: 23997 23998'``llvm.type.test``' Intrinsic 23999^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24000 24001Syntax: 24002""""""" 24003 24004:: 24005 24006 declare i1 @llvm.type.test(ptr %ptr, metadata %type) nounwind readnone 24007 24008 24009Arguments: 24010"""""""""" 24011 24012The first argument is a pointer to be tested. The second argument is a 24013metadata object representing a :doc:`type identifier <TypeMetadata>`. 24014 24015Overview: 24016""""""""" 24017 24018The ``llvm.type.test`` intrinsic tests whether the given pointer is associated 24019with the given type identifier. 24020 24021.. _type.checked.load: 24022 24023'``llvm.type.checked.load``' Intrinsic 24024^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24025 24026Syntax: 24027""""""" 24028 24029:: 24030 24031 declare {ptr, i1} @llvm.type.checked.load(ptr %ptr, i32 %offset, metadata %type) argmemonly nounwind readonly 24032 24033 24034Arguments: 24035"""""""""" 24036 24037The first argument is a pointer from which to load a function pointer. The 24038second argument is the byte offset from which to load the function pointer. The 24039third argument is a metadata object representing a :doc:`type identifier 24040<TypeMetadata>`. 24041 24042Overview: 24043""""""""" 24044 24045The ``llvm.type.checked.load`` intrinsic safely loads a function pointer from a 24046virtual table pointer using type metadata. This intrinsic is used to implement 24047control flow integrity in conjunction with virtual call optimization. The 24048virtual call optimization pass will optimize away ``llvm.type.checked.load`` 24049intrinsics associated with devirtualized calls, thereby removing the type 24050check in cases where it is not needed to enforce the control flow integrity 24051constraint. 24052 24053If the given pointer is associated with a type metadata identifier, this 24054function returns true as the second element of its return value. (Note that 24055the function may also return true if the given pointer is not associated 24056with a type metadata identifier.) If the function's return value's second 24057element is true, the following rules apply to the first element: 24058 24059- If the given pointer is associated with the given type metadata identifier, 24060 it is the function pointer loaded from the given byte offset from the given 24061 pointer. 24062 24063- If the given pointer is not associated with the given type metadata 24064 identifier, it is one of the following (the choice of which is unspecified): 24065 24066 1. The function pointer that would have been loaded from an arbitrarily chosen 24067 (through an unspecified mechanism) pointer associated with the type 24068 metadata. 24069 24070 2. If the function has a non-void return type, a pointer to a function that 24071 returns an unspecified value without causing side effects. 24072 24073If the function's return value's second element is false, the value of the 24074first element is undefined. 24075 24076 24077'``llvm.arithmetic.fence``' Intrinsic 24078^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24079 24080Syntax: 24081""""""" 24082 24083:: 24084 24085 declare <type> 24086 @llvm.arithmetic.fence(<type> <op>) 24087 24088Overview: 24089""""""""" 24090 24091The purpose of the ``llvm.arithmetic.fence`` intrinsic 24092is to prevent the optimizer from performing fast-math optimizations, 24093particularly reassociation, 24094between the argument and the expression that contains the argument. 24095It can be used to preserve the parentheses in the source language. 24096 24097Arguments: 24098"""""""""" 24099 24100The ``llvm.arithmetic.fence`` intrinsic takes only one argument. 24101The argument and the return value are floating-point numbers, 24102or vector floating-point numbers, of the same type. 24103 24104Semantics: 24105"""""""""" 24106 24107This intrinsic returns the value of its operand. The optimizer can optimize 24108the argument, but the optimizer cannot hoist any component of the operand 24109to the containing context, and the optimizer cannot move the calculation of 24110any expression in the containing context into the operand. 24111 24112 24113'``llvm.donothing``' Intrinsic 24114^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24115 24116Syntax: 24117""""""" 24118 24119:: 24120 24121 declare void @llvm.donothing() nounwind readnone 24122 24123Overview: 24124""""""""" 24125 24126The ``llvm.donothing`` intrinsic doesn't perform any operation. It's one of only 24127three intrinsics (besides ``llvm.experimental.patchpoint`` and 24128``llvm.experimental.gc.statepoint``) that can be called with an invoke 24129instruction. 24130 24131Arguments: 24132"""""""""" 24133 24134None. 24135 24136Semantics: 24137"""""""""" 24138 24139This intrinsic does nothing, and it's removed by optimizers and ignored 24140by codegen. 24141 24142'``llvm.experimental.deoptimize``' Intrinsic 24143^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24144 24145Syntax: 24146""""""" 24147 24148:: 24149 24150 declare type @llvm.experimental.deoptimize(...) [ "deopt"(...) ] 24151 24152Overview: 24153""""""""" 24154 24155This intrinsic, together with :ref:`deoptimization operand bundles 24156<deopt_opbundles>`, allow frontends to express transfer of control and 24157frame-local state from the currently executing (typically more specialized, 24158hence faster) version of a function into another (typically more generic, hence 24159slower) version. 24160 24161In languages with a fully integrated managed runtime like Java and JavaScript 24162this intrinsic can be used to implement "uncommon trap" or "side exit" like 24163functionality. In unmanaged languages like C and C++, this intrinsic can be 24164used to represent the slow paths of specialized functions. 24165 24166 24167Arguments: 24168"""""""""" 24169 24170The intrinsic takes an arbitrary number of arguments, whose meaning is 24171decided by the :ref:`lowering strategy<deoptimize_lowering>`. 24172 24173Semantics: 24174"""""""""" 24175 24176The ``@llvm.experimental.deoptimize`` intrinsic executes an attached 24177deoptimization continuation (denoted using a :ref:`deoptimization 24178operand bundle <deopt_opbundles>`) and returns the value returned by 24179the deoptimization continuation. Defining the semantic properties of 24180the continuation itself is out of scope of the language reference -- 24181as far as LLVM is concerned, the deoptimization continuation can 24182invoke arbitrary side effects, including reading from and writing to 24183the entire heap. 24184 24185Deoptimization continuations expressed using ``"deopt"`` operand bundles always 24186continue execution to the end of the physical frame containing them, so all 24187calls to ``@llvm.experimental.deoptimize`` must be in "tail position": 24188 24189 - ``@llvm.experimental.deoptimize`` cannot be invoked. 24190 - The call must immediately precede a :ref:`ret <i_ret>` instruction. 24191 - The ``ret`` instruction must return the value produced by the 24192 ``@llvm.experimental.deoptimize`` call if there is one, or void. 24193 24194Note that the above restrictions imply that the return type for a call to 24195``@llvm.experimental.deoptimize`` will match the return type of its immediate 24196caller. 24197 24198The inliner composes the ``"deopt"`` continuations of the caller into the 24199``"deopt"`` continuations present in the inlinee, and also updates calls to this 24200intrinsic to return directly from the frame of the function it inlined into. 24201 24202All declarations of ``@llvm.experimental.deoptimize`` must share the 24203same calling convention. 24204 24205.. _deoptimize_lowering: 24206 24207Lowering: 24208""""""""" 24209 24210Calls to ``@llvm.experimental.deoptimize`` are lowered to calls to the 24211symbol ``__llvm_deoptimize`` (it is the frontend's responsibility to 24212ensure that this symbol is defined). The call arguments to 24213``@llvm.experimental.deoptimize`` are lowered as if they were formal 24214arguments of the specified types, and not as varargs. 24215 24216 24217'``llvm.experimental.guard``' Intrinsic 24218^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24219 24220Syntax: 24221""""""" 24222 24223:: 24224 24225 declare void @llvm.experimental.guard(i1, ...) [ "deopt"(...) ] 24226 24227Overview: 24228""""""""" 24229 24230This intrinsic, together with :ref:`deoptimization operand bundles 24231<deopt_opbundles>`, allows frontends to express guards or checks on 24232optimistic assumptions made during compilation. The semantics of 24233``@llvm.experimental.guard`` is defined in terms of 24234``@llvm.experimental.deoptimize`` -- its body is defined to be 24235equivalent to: 24236 24237.. code-block:: text 24238 24239 define void @llvm.experimental.guard(i1 %pred, <args...>) { 24240 %realPred = and i1 %pred, undef 24241 br i1 %realPred, label %continue, label %leave [, !make.implicit !{}] 24242 24243 leave: 24244 call void @llvm.experimental.deoptimize(<args...>) [ "deopt"() ] 24245 ret void 24246 24247 continue: 24248 ret void 24249 } 24250 24251 24252with the optional ``[, !make.implicit !{}]`` present if and only if it 24253is present on the call site. For more details on ``!make.implicit``, 24254see :doc:`FaultMaps`. 24255 24256In words, ``@llvm.experimental.guard`` executes the attached 24257``"deopt"`` continuation if (but **not** only if) its first argument 24258is ``false``. Since the optimizer is allowed to replace the ``undef`` 24259with an arbitrary value, it can optimize guard to fail "spuriously", 24260i.e. without the original condition being false (hence the "not only 24261if"); and this allows for "check widening" type optimizations. 24262 24263``@llvm.experimental.guard`` cannot be invoked. 24264 24265After ``@llvm.experimental.guard`` was first added, a more general 24266formulation was found in ``@llvm.experimental.widenable.condition``. 24267Support for ``@llvm.experimental.guard`` is slowly being rephrased in 24268terms of this alternate. 24269 24270'``llvm.experimental.widenable.condition``' Intrinsic 24271^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24272 24273Syntax: 24274""""""" 24275 24276:: 24277 24278 declare i1 @llvm.experimental.widenable.condition() 24279 24280Overview: 24281""""""""" 24282 24283This intrinsic represents a "widenable condition" which is 24284boolean expressions with the following property: whether this 24285expression is `true` or `false`, the program is correct and 24286well-defined. 24287 24288Together with :ref:`deoptimization operand bundles <deopt_opbundles>`, 24289``@llvm.experimental.widenable.condition`` allows frontends to 24290express guards or checks on optimistic assumptions made during 24291compilation and represent them as branch instructions on special 24292conditions. 24293 24294While this may appear similar in semantics to `undef`, it is very 24295different in that an invocation produces a particular, singular 24296value. It is also intended to be lowered late, and remain available 24297for specific optimizations and transforms that can benefit from its 24298special properties. 24299 24300Arguments: 24301"""""""""" 24302 24303None. 24304 24305Semantics: 24306"""""""""" 24307 24308The intrinsic ``@llvm.experimental.widenable.condition()`` 24309returns either `true` or `false`. For each evaluation of a call 24310to this intrinsic, the program must be valid and correct both if 24311it returns `true` and if it returns `false`. This allows 24312transformation passes to replace evaluations of this intrinsic 24313with either value whenever one is beneficial. 24314 24315When used in a branch condition, it allows us to choose between 24316two alternative correct solutions for the same problem, like 24317in example below: 24318 24319.. code-block:: text 24320 24321 %cond = call i1 @llvm.experimental.widenable.condition() 24322 br i1 %cond, label %solution_1, label %solution_2 24323 24324 label %fast_path: 24325 ; Apply memory-consuming but fast solution for a task. 24326 24327 label %slow_path: 24328 ; Cheap in memory but slow solution. 24329 24330Whether the result of intrinsic's call is `true` or `false`, 24331it should be correct to pick either solution. We can switch 24332between them by replacing the result of 24333``@llvm.experimental.widenable.condition`` with different 24334`i1` expressions. 24335 24336This is how it can be used to represent guards as widenable branches: 24337 24338.. code-block:: text 24339 24340 block: 24341 ; Unguarded instructions 24342 call void @llvm.experimental.guard(i1 %cond, <args...>) ["deopt"(<deopt_args...>)] 24343 ; Guarded instructions 24344 24345Can be expressed in an alternative equivalent form of explicit branch using 24346``@llvm.experimental.widenable.condition``: 24347 24348.. code-block:: text 24349 24350 block: 24351 ; Unguarded instructions 24352 %widenable_condition = call i1 @llvm.experimental.widenable.condition() 24353 %guard_condition = and i1 %cond, %widenable_condition 24354 br i1 %guard_condition, label %guarded, label %deopt 24355 24356 guarded: 24357 ; Guarded instructions 24358 24359 deopt: 24360 call type @llvm.experimental.deoptimize(<args...>) [ "deopt"(<deopt_args...>) ] 24361 24362So the block `guarded` is only reachable when `%cond` is `true`, 24363and it should be valid to go to the block `deopt` whenever `%cond` 24364is `true` or `false`. 24365 24366``@llvm.experimental.widenable.condition`` will never throw, thus 24367it cannot be invoked. 24368 24369Guard widening: 24370""""""""""""""" 24371 24372When ``@llvm.experimental.widenable.condition()`` is used in 24373condition of a guard represented as explicit branch, it is 24374legal to widen the guard's condition with any additional 24375conditions. 24376 24377Guard widening looks like replacement of 24378 24379.. code-block:: text 24380 24381 %widenable_cond = call i1 @llvm.experimental.widenable.condition() 24382 %guard_cond = and i1 %cond, %widenable_cond 24383 br i1 %guard_cond, label %guarded, label %deopt 24384 24385with 24386 24387.. code-block:: text 24388 24389 %widenable_cond = call i1 @llvm.experimental.widenable.condition() 24390 %new_cond = and i1 %any_other_cond, %widenable_cond 24391 %new_guard_cond = and i1 %cond, %new_cond 24392 br i1 %new_guard_cond, label %guarded, label %deopt 24393 24394for this branch. Here `%any_other_cond` is an arbitrarily chosen 24395well-defined `i1` value. By making guard widening, we may 24396impose stricter conditions on `guarded` block and bail to the 24397deopt when the new condition is not met. 24398 24399Lowering: 24400""""""""" 24401 24402Default lowering strategy is replacing the result of 24403call of ``@llvm.experimental.widenable.condition`` with 24404constant `true`. However it is always correct to replace 24405it with any other `i1` value. Any pass can 24406freely do it if it can benefit from non-default lowering. 24407 24408 24409'``llvm.load.relative``' Intrinsic 24410^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24411 24412Syntax: 24413""""""" 24414 24415:: 24416 24417 declare ptr @llvm.load.relative.iN(ptr %ptr, iN %offset) argmemonly nounwind readonly 24418 24419Overview: 24420""""""""" 24421 24422This intrinsic loads a 32-bit value from the address ``%ptr + %offset``, 24423adds ``%ptr`` to that value and returns it. The constant folder specifically 24424recognizes the form of this intrinsic and the constant initializers it may 24425load from; if a loaded constant initializer is known to have the form 24426``i32 trunc(x - %ptr)``, the intrinsic call is folded to ``x``. 24427 24428LLVM provides that the calculation of such a constant initializer will 24429not overflow at link time under the medium code model if ``x`` is an 24430``unnamed_addr`` function. However, it does not provide this guarantee for 24431a constant initializer folded into a function body. This intrinsic can be 24432used to avoid the possibility of overflows when loading from such a constant. 24433 24434.. _llvm_sideeffect: 24435 24436'``llvm.sideeffect``' Intrinsic 24437^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24438 24439Syntax: 24440""""""" 24441 24442:: 24443 24444 declare void @llvm.sideeffect() inaccessiblememonly nounwind willreturn 24445 24446Overview: 24447""""""""" 24448 24449The ``llvm.sideeffect`` intrinsic doesn't perform any operation. Optimizers 24450treat it as having side effects, so it can be inserted into a loop to 24451indicate that the loop shouldn't be assumed to terminate (which could 24452potentially lead to the loop being optimized away entirely), even if it's 24453an infinite loop with no other side effects. 24454 24455Arguments: 24456"""""""""" 24457 24458None. 24459 24460Semantics: 24461"""""""""" 24462 24463This intrinsic actually does nothing, but optimizers must assume that it 24464has externally observable side effects. 24465 24466'``llvm.is.constant.*``' Intrinsic 24467^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24468 24469Syntax: 24470""""""" 24471 24472This is an overloaded intrinsic. You can use llvm.is.constant with any argument type. 24473 24474:: 24475 24476 declare i1 @llvm.is.constant.i32(i32 %operand) nounwind readnone 24477 declare i1 @llvm.is.constant.f32(float %operand) nounwind readnone 24478 declare i1 @llvm.is.constant.TYPENAME(TYPE %operand) nounwind readnone 24479 24480Overview: 24481""""""""" 24482 24483The '``llvm.is.constant``' intrinsic will return true if the argument 24484is known to be a manifest compile-time constant. It is guaranteed to 24485fold to either true or false before generating machine code. 24486 24487Semantics: 24488"""""""""" 24489 24490This intrinsic generates no code. If its argument is known to be a 24491manifest compile-time constant value, then the intrinsic will be 24492converted to a constant true value. Otherwise, it will be converted to 24493a constant false value. 24494 24495In particular, note that if the argument is a constant expression 24496which refers to a global (the address of which _is_ a constant, but 24497not manifest during the compile), then the intrinsic evaluates to 24498false. 24499 24500The result also intentionally depends on the result of optimization 24501passes -- e.g., the result can change depending on whether a 24502function gets inlined or not. A function's parameters are 24503obviously not constant. However, a call like 24504``llvm.is.constant.i32(i32 %param)`` *can* return true after the 24505function is inlined, if the value passed to the function parameter was 24506a constant. 24507 24508On the other hand, if constant folding is not run, it will never 24509evaluate to true, even in simple cases. 24510 24511.. _int_ptrmask: 24512 24513'``llvm.ptrmask``' Intrinsic 24514^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24515 24516Syntax: 24517""""""" 24518 24519:: 24520 24521 declare ptrty llvm.ptrmask(ptrty %ptr, intty %mask) readnone speculatable 24522 24523Arguments: 24524"""""""""" 24525 24526The first argument is a pointer. The second argument is an integer. 24527 24528Overview: 24529"""""""""" 24530 24531The ``llvm.ptrmask`` intrinsic masks out bits of the pointer according to a mask. 24532This allows stripping data from tagged pointers without converting them to an 24533integer (ptrtoint/inttoptr). As a consequence, we can preserve more information 24534to facilitate alias analysis and underlying-object detection. 24535 24536Semantics: 24537"""""""""" 24538 24539The result of ``ptrmask(ptr, mask)`` is equivalent to 24540``getelementptr ptr, (ptrtoint(ptr) & mask) - ptrtoint(ptr)``. Both the returned 24541pointer and the first argument are based on the same underlying object (for more 24542information on the *based on* terminology see 24543:ref:`the pointer aliasing rules <pointeraliasing>`). If the bitwidth of the 24544mask argument does not match the pointer size of the target, the mask is 24545zero-extended or truncated accordingly. 24546 24547.. _int_vscale: 24548 24549'``llvm.vscale``' Intrinsic 24550^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24551 24552Syntax: 24553""""""" 24554 24555:: 24556 24557 declare i32 llvm.vscale.i32() 24558 declare i64 llvm.vscale.i64() 24559 24560Overview: 24561""""""""" 24562 24563The ``llvm.vscale`` intrinsic returns the value for ``vscale`` in scalable 24564vectors such as ``<vscale x 16 x i8>``. 24565 24566Semantics: 24567"""""""""" 24568 24569``vscale`` is a positive value that is constant throughout program 24570execution, but is unknown at compile time. 24571If the result value does not fit in the result type, then the result is 24572a :ref:`poison value <poisonvalues>`. 24573 24574 24575Stack Map Intrinsics 24576-------------------- 24577 24578LLVM provides experimental intrinsics to support runtime patching 24579mechanisms commonly desired in dynamic language JITs. These intrinsics 24580are described in :doc:`StackMaps`. 24581 24582Element Wise Atomic Memory Intrinsics 24583------------------------------------- 24584 24585These intrinsics are similar to the standard library memory intrinsics except 24586that they perform memory transfer as a sequence of atomic memory accesses. 24587 24588.. _int_memcpy_element_unordered_atomic: 24589 24590'``llvm.memcpy.element.unordered.atomic``' Intrinsic 24591^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24592 24593Syntax: 24594""""""" 24595 24596This is an overloaded intrinsic. You can use ``llvm.memcpy.element.unordered.atomic`` on 24597any integer bit width and for different address spaces. Not all targets 24598support all bit widths however. 24599 24600:: 24601 24602 declare void @llvm.memcpy.element.unordered.atomic.p0.p0.i32(ptr <dest>, 24603 ptr <src>, 24604 i32 <len>, 24605 i32 <element_size>) 24606 declare void @llvm.memcpy.element.unordered.atomic.p0.p0.i64(ptr <dest>, 24607 ptr <src>, 24608 i64 <len>, 24609 i32 <element_size>) 24610 24611Overview: 24612""""""""" 24613 24614The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic is a specialization of the 24615'``llvm.memcpy.*``' intrinsic. It differs in that the ``dest`` and ``src`` are treated 24616as arrays with elements that are exactly ``element_size`` bytes, and the copy between 24617buffers uses a sequence of :ref:`unordered atomic <ordering>` load/store operations 24618that are a positive integer multiple of the ``element_size`` in size. 24619 24620Arguments: 24621"""""""""" 24622 24623The first three arguments are the same as they are in the :ref:`@llvm.memcpy <int_memcpy>` 24624intrinsic, with the added constraint that ``len`` is required to be a positive integer 24625multiple of the ``element_size``. If ``len`` is not a positive integer multiple of 24626``element_size``, then the behaviour of the intrinsic is undefined. 24627 24628``element_size`` must be a compile-time constant positive power of two no greater than 24629target-specific atomic access size limit. 24630 24631For each of the input pointers ``align`` parameter attribute must be specified. It 24632must be a power of two no less than the ``element_size``. Caller guarantees that 24633both the source and destination pointers are aligned to that boundary. 24634 24635Semantics: 24636"""""""""" 24637 24638The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic copies ``len`` bytes of 24639memory from the source location to the destination location. These locations are not 24640allowed to overlap. The memory copy is performed as a sequence of load/store operations 24641where each access is guaranteed to be a multiple of ``element_size`` bytes wide and 24642aligned at an ``element_size`` boundary. 24643 24644The order of the copy is unspecified. The same value may be read from the source 24645buffer many times, but only one write is issued to the destination buffer per 24646element. It is well defined to have concurrent reads and writes to both source and 24647destination provided those reads and writes are unordered atomic when specified. 24648 24649This intrinsic does not provide any additional ordering guarantees over those 24650provided by a set of unordered loads from the source location and stores to the 24651destination. 24652 24653Lowering: 24654""""""""" 24655 24656In the most general case call to the '``llvm.memcpy.element.unordered.atomic.*``' is 24657lowered to a call to the symbol ``__llvm_memcpy_element_unordered_atomic_*``. Where '*' 24658is replaced with an actual element size. See :ref:`RewriteStatepointsForGC intrinsic 24659lowering <RewriteStatepointsForGC_intrinsic_lowering>` for details on GC specific 24660lowering. 24661 24662Optimizer is allowed to inline memory copy when it's profitable to do so. 24663 24664'``llvm.memmove.element.unordered.atomic``' Intrinsic 24665^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24666 24667Syntax: 24668""""""" 24669 24670This is an overloaded intrinsic. You can use 24671``llvm.memmove.element.unordered.atomic`` on any integer bit width and for 24672different address spaces. Not all targets support all bit widths however. 24673 24674:: 24675 24676 declare void @llvm.memmove.element.unordered.atomic.p0.p0.i32(ptr <dest>, 24677 ptr <src>, 24678 i32 <len>, 24679 i32 <element_size>) 24680 declare void @llvm.memmove.element.unordered.atomic.p0.p0.i64(ptr <dest>, 24681 ptr <src>, 24682 i64 <len>, 24683 i32 <element_size>) 24684 24685Overview: 24686""""""""" 24687 24688The '``llvm.memmove.element.unordered.atomic.*``' intrinsic is a specialization 24689of the '``llvm.memmove.*``' intrinsic. It differs in that the ``dest`` and 24690``src`` are treated as arrays with elements that are exactly ``element_size`` 24691bytes, and the copy between buffers uses a sequence of 24692:ref:`unordered atomic <ordering>` load/store operations that are a positive 24693integer multiple of the ``element_size`` in size. 24694 24695Arguments: 24696"""""""""" 24697 24698The first three arguments are the same as they are in the 24699:ref:`@llvm.memmove <int_memmove>` intrinsic, with the added constraint that 24700``len`` is required to be a positive integer multiple of the ``element_size``. 24701If ``len`` is not a positive integer multiple of ``element_size``, then the 24702behaviour of the intrinsic is undefined. 24703 24704``element_size`` must be a compile-time constant positive power of two no 24705greater than a target-specific atomic access size limit. 24706 24707For each of the input pointers the ``align`` parameter attribute must be 24708specified. It must be a power of two no less than the ``element_size``. Caller 24709guarantees that both the source and destination pointers are aligned to that 24710boundary. 24711 24712Semantics: 24713"""""""""" 24714 24715The '``llvm.memmove.element.unordered.atomic.*``' intrinsic copies ``len`` bytes 24716of memory from the source location to the destination location. These locations 24717are allowed to overlap. The memory copy is performed as a sequence of load/store 24718operations where each access is guaranteed to be a multiple of ``element_size`` 24719bytes wide and aligned at an ``element_size`` boundary. 24720 24721The order of the copy is unspecified. The same value may be read from the source 24722buffer many times, but only one write is issued to the destination buffer per 24723element. It is well defined to have concurrent reads and writes to both source 24724and destination provided those reads and writes are unordered atomic when 24725specified. 24726 24727This intrinsic does not provide any additional ordering guarantees over those 24728provided by a set of unordered loads from the source location and stores to the 24729destination. 24730 24731Lowering: 24732""""""""" 24733 24734In the most general case call to the 24735'``llvm.memmove.element.unordered.atomic.*``' is lowered to a call to the symbol 24736``__llvm_memmove_element_unordered_atomic_*``. Where '*' is replaced with an 24737actual element size. See :ref:`RewriteStatepointsForGC intrinsic lowering 24738<RewriteStatepointsForGC_intrinsic_lowering>` for details on GC specific 24739lowering. 24740 24741The optimizer is allowed to inline the memory copy when it's profitable to do so. 24742 24743.. _int_memset_element_unordered_atomic: 24744 24745'``llvm.memset.element.unordered.atomic``' Intrinsic 24746^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24747 24748Syntax: 24749""""""" 24750 24751This is an overloaded intrinsic. You can use ``llvm.memset.element.unordered.atomic`` on 24752any integer bit width and for different address spaces. Not all targets 24753support all bit widths however. 24754 24755:: 24756 24757 declare void @llvm.memset.element.unordered.atomic.p0.i32(ptr <dest>, 24758 i8 <value>, 24759 i32 <len>, 24760 i32 <element_size>) 24761 declare void @llvm.memset.element.unordered.atomic.p0.i64(ptr <dest>, 24762 i8 <value>, 24763 i64 <len>, 24764 i32 <element_size>) 24765 24766Overview: 24767""""""""" 24768 24769The '``llvm.memset.element.unordered.atomic.*``' intrinsic is a specialization of the 24770'``llvm.memset.*``' intrinsic. It differs in that the ``dest`` is treated as an array 24771with elements that are exactly ``element_size`` bytes, and the assignment to that array 24772uses uses a sequence of :ref:`unordered atomic <ordering>` store operations 24773that are a positive integer multiple of the ``element_size`` in size. 24774 24775Arguments: 24776"""""""""" 24777 24778The first three arguments are the same as they are in the :ref:`@llvm.memset <int_memset>` 24779intrinsic, with the added constraint that ``len`` is required to be a positive integer 24780multiple of the ``element_size``. If ``len`` is not a positive integer multiple of 24781``element_size``, then the behaviour of the intrinsic is undefined. 24782 24783``element_size`` must be a compile-time constant positive power of two no greater than 24784target-specific atomic access size limit. 24785 24786The ``dest`` input pointer must have the ``align`` parameter attribute specified. It 24787must be a power of two no less than the ``element_size``. Caller guarantees that 24788the destination pointer is aligned to that boundary. 24789 24790Semantics: 24791"""""""""" 24792 24793The '``llvm.memset.element.unordered.atomic.*``' intrinsic sets the ``len`` bytes of 24794memory starting at the destination location to the given ``value``. The memory is 24795set with a sequence of store operations where each access is guaranteed to be a 24796multiple of ``element_size`` bytes wide and aligned at an ``element_size`` boundary. 24797 24798The order of the assignment is unspecified. Only one write is issued to the 24799destination buffer per element. It is well defined to have concurrent reads and 24800writes to the destination provided those reads and writes are unordered atomic 24801when specified. 24802 24803This intrinsic does not provide any additional ordering guarantees over those 24804provided by a set of unordered stores to the destination. 24805 24806Lowering: 24807""""""""" 24808 24809In the most general case call to the '``llvm.memset.element.unordered.atomic.*``' is 24810lowered to a call to the symbol ``__llvm_memset_element_unordered_atomic_*``. Where '*' 24811is replaced with an actual element size. 24812 24813The optimizer is allowed to inline the memory assignment when it's profitable to do so. 24814 24815Objective-C ARC Runtime Intrinsics 24816---------------------------------- 24817 24818LLVM provides intrinsics that lower to Objective-C ARC runtime entry points. 24819LLVM is aware of the semantics of these functions, and optimizes based on that 24820knowledge. You can read more about the details of Objective-C ARC `here 24821<https://clang.llvm.org/docs/AutomaticReferenceCounting.html>`_. 24822 24823'``llvm.objc.autorelease``' Intrinsic 24824^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24825 24826Syntax: 24827""""""" 24828:: 24829 24830 declare ptr @llvm.objc.autorelease(ptr) 24831 24832Lowering: 24833""""""""" 24834 24835Lowers to a call to `objc_autorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autorelease>`_. 24836 24837'``llvm.objc.autoreleasePoolPop``' Intrinsic 24838^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24839 24840Syntax: 24841""""""" 24842:: 24843 24844 declare void @llvm.objc.autoreleasePoolPop(ptr) 24845 24846Lowering: 24847""""""""" 24848 24849Lowers to a call to `objc_autoreleasePoolPop <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpop-void-pool>`_. 24850 24851'``llvm.objc.autoreleasePoolPush``' Intrinsic 24852^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24853 24854Syntax: 24855""""""" 24856:: 24857 24858 declare ptr @llvm.objc.autoreleasePoolPush() 24859 24860Lowering: 24861""""""""" 24862 24863Lowers to a call to `objc_autoreleasePoolPush <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpush-void>`_. 24864 24865'``llvm.objc.autoreleaseReturnValue``' Intrinsic 24866^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24867 24868Syntax: 24869""""""" 24870:: 24871 24872 declare ptr @llvm.objc.autoreleaseReturnValue(ptr) 24873 24874Lowering: 24875""""""""" 24876 24877Lowers to a call to `objc_autoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autoreleasereturnvalue>`_. 24878 24879'``llvm.objc.copyWeak``' Intrinsic 24880^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24881 24882Syntax: 24883""""""" 24884:: 24885 24886 declare void @llvm.objc.copyWeak(ptr, ptr) 24887 24888Lowering: 24889""""""""" 24890 24891Lowers to a call to `objc_copyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-copyweak-id-dest-id-src>`_. 24892 24893'``llvm.objc.destroyWeak``' Intrinsic 24894^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24895 24896Syntax: 24897""""""" 24898:: 24899 24900 declare void @llvm.objc.destroyWeak(ptr) 24901 24902Lowering: 24903""""""""" 24904 24905Lowers to a call to `objc_destroyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-destroyweak-id-object>`_. 24906 24907'``llvm.objc.initWeak``' Intrinsic 24908^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24909 24910Syntax: 24911""""""" 24912:: 24913 24914 declare ptr @llvm.objc.initWeak(ptr, ptr) 24915 24916Lowering: 24917""""""""" 24918 24919Lowers to a call to `objc_initWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-initweak>`_. 24920 24921'``llvm.objc.loadWeak``' Intrinsic 24922^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24923 24924Syntax: 24925""""""" 24926:: 24927 24928 declare ptr @llvm.objc.loadWeak(ptr) 24929 24930Lowering: 24931""""""""" 24932 24933Lowers to a call to `objc_loadWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweak>`_. 24934 24935'``llvm.objc.loadWeakRetained``' Intrinsic 24936^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24937 24938Syntax: 24939""""""" 24940:: 24941 24942 declare ptr @llvm.objc.loadWeakRetained(ptr) 24943 24944Lowering: 24945""""""""" 24946 24947Lowers to a call to `objc_loadWeakRetained <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweakretained>`_. 24948 24949'``llvm.objc.moveWeak``' Intrinsic 24950^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24951 24952Syntax: 24953""""""" 24954:: 24955 24956 declare void @llvm.objc.moveWeak(ptr, ptr) 24957 24958Lowering: 24959""""""""" 24960 24961Lowers to a call to `objc_moveWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-moveweak-id-dest-id-src>`_. 24962 24963'``llvm.objc.release``' Intrinsic 24964^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24965 24966Syntax: 24967""""""" 24968:: 24969 24970 declare void @llvm.objc.release(ptr) 24971 24972Lowering: 24973""""""""" 24974 24975Lowers to a call to `objc_release <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-release-id-value>`_. 24976 24977'``llvm.objc.retain``' Intrinsic 24978^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24979 24980Syntax: 24981""""""" 24982:: 24983 24984 declare ptr @llvm.objc.retain(ptr) 24985 24986Lowering: 24987""""""""" 24988 24989Lowers to a call to `objc_retain <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retain>`_. 24990 24991'``llvm.objc.retainAutorelease``' Intrinsic 24992^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 24993 24994Syntax: 24995""""""" 24996:: 24997 24998 declare ptr @llvm.objc.retainAutorelease(ptr) 24999 25000Lowering: 25001""""""""" 25002 25003Lowers to a call to `objc_retainAutorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautorelease>`_. 25004 25005'``llvm.objc.retainAutoreleaseReturnValue``' Intrinsic 25006^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25007 25008Syntax: 25009""""""" 25010:: 25011 25012 declare ptr @llvm.objc.retainAutoreleaseReturnValue(ptr) 25013 25014Lowering: 25015""""""""" 25016 25017Lowers to a call to `objc_retainAutoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasereturnvalue>`_. 25018 25019'``llvm.objc.retainAutoreleasedReturnValue``' Intrinsic 25020^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25021 25022Syntax: 25023""""""" 25024:: 25025 25026 declare ptr @llvm.objc.retainAutoreleasedReturnValue(ptr) 25027 25028Lowering: 25029""""""""" 25030 25031Lowers to a call to `objc_retainAutoreleasedReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasedreturnvalue>`_. 25032 25033'``llvm.objc.retainBlock``' Intrinsic 25034^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25035 25036Syntax: 25037""""""" 25038:: 25039 25040 declare ptr @llvm.objc.retainBlock(ptr) 25041 25042Lowering: 25043""""""""" 25044 25045Lowers to a call to `objc_retainBlock <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainblock>`_. 25046 25047'``llvm.objc.storeStrong``' Intrinsic 25048^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25049 25050Syntax: 25051""""""" 25052:: 25053 25054 declare void @llvm.objc.storeStrong(ptr, ptr) 25055 25056Lowering: 25057""""""""" 25058 25059Lowers to a call to `objc_storeStrong <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-storestrong-id-object-id-value>`_. 25060 25061'``llvm.objc.storeWeak``' Intrinsic 25062^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25063 25064Syntax: 25065""""""" 25066:: 25067 25068 declare ptr @llvm.objc.storeWeak(ptr, ptr) 25069 25070Lowering: 25071""""""""" 25072 25073Lowers to a call to `objc_storeWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-storeweak>`_. 25074 25075Preserving Debug Information Intrinsics 25076^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25077 25078These intrinsics are used to carry certain debuginfo together with 25079IR-level operations. For example, it may be desirable to 25080know the structure/union name and the original user-level field 25081indices. Such information got lost in IR GetElementPtr instruction 25082since the IR types are different from debugInfo types and unions 25083are converted to structs in IR. 25084 25085'``llvm.preserve.array.access.index``' Intrinsic 25086^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25087 25088Syntax: 25089""""""" 25090:: 25091 25092 declare <ret_type> 25093 @llvm.preserve.array.access.index.p0s_union.anons.p0a10s_union.anons(<type> base, 25094 i32 dim, 25095 i32 index) 25096 25097Overview: 25098""""""""" 25099 25100The '``llvm.preserve.array.access.index``' intrinsic returns the getelementptr address 25101based on array base ``base``, array dimension ``dim`` and the last access index ``index`` 25102into the array. The return type ``ret_type`` is a pointer type to the array element. 25103The array ``dim`` and ``index`` are preserved which is more robust than 25104getelementptr instruction which may be subject to compiler transformation. 25105The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction 25106to provide array or pointer debuginfo type. 25107The metadata is a ``DICompositeType`` or ``DIDerivedType`` representing the 25108debuginfo version of ``type``. 25109 25110Arguments: 25111"""""""""" 25112 25113The ``base`` is the array base address. The ``dim`` is the array dimension. 25114The ``base`` is a pointer if ``dim`` equals 0. 25115The ``index`` is the last access index into the array or pointer. 25116 25117The ``base`` argument must be annotated with an :ref:`elementtype 25118<attr_elementtype>` attribute at the call-site. This attribute specifies the 25119getelementptr element type. 25120 25121Semantics: 25122"""""""""" 25123 25124The '``llvm.preserve.array.access.index``' intrinsic produces the same result 25125as a getelementptr with base ``base`` and access operands ``{dim's 0's, index}``. 25126 25127'``llvm.preserve.union.access.index``' Intrinsic 25128^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25129 25130Syntax: 25131""""""" 25132:: 25133 25134 declare <type> 25135 @llvm.preserve.union.access.index.p0s_union.anons.p0s_union.anons(<type> base, 25136 i32 di_index) 25137 25138Overview: 25139""""""""" 25140 25141The '``llvm.preserve.union.access.index``' intrinsic carries the debuginfo field index 25142``di_index`` and returns the ``base`` address. 25143The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction 25144to provide union debuginfo type. 25145The metadata is a ``DICompositeType`` representing the debuginfo version of ``type``. 25146The return type ``type`` is the same as the ``base`` type. 25147 25148Arguments: 25149"""""""""" 25150 25151The ``base`` is the union base address. The ``di_index`` is the field index in debuginfo. 25152 25153Semantics: 25154"""""""""" 25155 25156The '``llvm.preserve.union.access.index``' intrinsic returns the ``base`` address. 25157 25158'``llvm.preserve.struct.access.index``' Intrinsic 25159^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25160 25161Syntax: 25162""""""" 25163:: 25164 25165 declare <ret_type> 25166 @llvm.preserve.struct.access.index.p0i8.p0s_struct.anon.0s(<type> base, 25167 i32 gep_index, 25168 i32 di_index) 25169 25170Overview: 25171""""""""" 25172 25173The '``llvm.preserve.struct.access.index``' intrinsic returns the getelementptr address 25174based on struct base ``base`` and IR struct member index ``gep_index``. 25175The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction 25176to provide struct debuginfo type. 25177The metadata is a ``DICompositeType`` representing the debuginfo version of ``type``. 25178The return type ``ret_type`` is a pointer type to the structure member. 25179 25180Arguments: 25181"""""""""" 25182 25183The ``base`` is the structure base address. The ``gep_index`` is the struct member index 25184based on IR structures. The ``di_index`` is the struct member index based on debuginfo. 25185 25186The ``base`` argument must be annotated with an :ref:`elementtype 25187<attr_elementtype>` attribute at the call-site. This attribute specifies the 25188getelementptr element type. 25189 25190Semantics: 25191"""""""""" 25192 25193The '``llvm.preserve.struct.access.index``' intrinsic produces the same result 25194as a getelementptr with base ``base`` and access operands ``{0, gep_index}``. 25195 25196'``llvm.fptrunc.round``' Intrinsic 25197^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 25198 25199Syntax: 25200""""""" 25201 25202:: 25203 25204 declare <ty2> 25205 @llvm.fptrunc.round(<type> <value>, metadata <rounding mode>) 25206 25207Overview: 25208""""""""" 25209 25210The '``llvm.fptrunc.round``' intrinsic truncates 25211:ref:`floating-point <t_floating>` ``value`` to type ``ty2`` 25212with a specified rounding mode. 25213 25214Arguments: 25215"""""""""" 25216 25217The '``llvm.fptrunc.round``' intrinsic takes a :ref:`floating-point 25218<t_floating>` value to cast and a :ref:`floating-point <t_floating>` type 25219to cast it to. This argument must be larger in size than the result. 25220 25221The second argument specifies the rounding mode as described in the constrained 25222intrinsics section. 25223For this intrinsic, the "round.dynamic" mode is not supported. 25224 25225Semantics: 25226"""""""""" 25227 25228The '``llvm.fptrunc.round``' intrinsic casts a ``value`` from a larger 25229:ref:`floating-point <t_floating>` type to a smaller :ref:`floating-point 25230<t_floating>` type. 25231This intrinsic is assumed to execute in the default :ref:`floating-point 25232environment <floatenv>` *except* for the rounding mode. 25233This intrinsic is not supported on all targets. Some targets may not support 25234all rounding modes. 25235