diff options
Diffstat (limited to 'docs/LangRef.rst')
| -rw-r--r-- | docs/LangRef.rst | 493 |
1 files changed, 349 insertions, 144 deletions
diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 5c65864e901e..589786255af7 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -527,6 +527,24 @@ the alias is accessed. It will not have any effect in the aliasee. For platforms without linker support of ELF TLS model, the -femulated-tls flag can be used to generate GCC compatible emulated TLS code. +.. _runtime_preemption_model: + +Runtime Preemption Specifiers +----------------------------- + +Global variables, functions and aliases may have an optional runtime preemption +specifier. If a preemption specifier isn't given explicitly, then a +symbol is assumed to be ``dso_preemptable``. + +``dso_preemptable`` + Indicates that the function or variable may be replaced by a symbol from + outside the linkage unit at runtime. + +``dso_local`` + The compiler may assume that a function or variable marked as ``dso_local`` + will resolve to a symbol within the same linkage unit. Direct access will + be generated even if the definition is not within this compilation unit. + .. _namedtypes: Structure Types @@ -579,7 +597,9 @@ Global variables in other translation units can also be declared, in which case they don't have an initializer. Either global variable definitions or declarations may have an explicit section -to be placed in and may have an optional explicit alignment specified. +to be placed in and may have an optional explicit alignment specified. If there +is a mismatch between the explicit or inferred section information for the +variable declaration and its definition the resulting behavior is undefined. A variable may be defined as a global ``constant``, which indicates that the contents of the variable will **never** be modified (enabling better @@ -622,6 +642,12 @@ target supports it, it will emit globals to the section specified. Additionally, the global can placed in a comdat if the target has the necessary support. +External declarations may have an explicit section specified. Section +information is retained in LLVM IR for targets that make use of this +information. Attaching section information to an external declaration is an +assertion that its definition is located in the specified section. If the +definition is located in a different section, the behavior is undefined. + By default, global initializers are optimized by assuming that global variables defined within the module are not modified from their initial values before the start of the global initializer. This is @@ -642,6 +668,7 @@ iterate over them as an array, alignment padding would break this iteration. The maximum alignment is ``1 << 29``. Globals can also have a :ref:`DLL storage class <dllstorageclass>`, +an optional :ref:`runtime preemption specifier <runtime_preemption_model>`, an optional :ref:`global attributes <glattrs>` and an optional list of attached :ref:`metadata <metadata>`. @@ -650,7 +677,8 @@ Variables and aliases can have a Syntax:: - @<GlobalVarName> = [Linkage] [Visibility] [DLLStorageClass] [ThreadLocal] + @<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility] + [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [ExternallyInitialized] <global | constant> <Type> [<InitializerConstant>] @@ -683,7 +711,8 @@ Functions --------- LLVM function definitions consist of the "``define``" keyword, an -optional :ref:`linkage type <linkage>`, an optional :ref:`visibility +optional :ref:`linkage type <linkage>`, an optional :ref:`runtime preemption +specifier <runtime_preemption_model>`, an optional :ref:`visibility style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, an optional :ref:`calling convention <callingconv>`, an optional ``unnamed_addr`` attribute, a return type, an optional @@ -742,7 +771,7 @@ not be significant within the module. Syntax:: - define [linkage] [visibility] [DLLStorageClass] + define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass] [cconv] [ret attrs] <ResultType> @<FunctionName> ([argument list]) [(unnamed_addr|local_unnamed_addr)] [fn Attrs] [section "name"] @@ -769,12 +798,13 @@ Aliases have a name and an aliasee that is either a global value or a constant expression. Aliases may have an optional :ref:`linkage type <linkage>`, an optional +:ref:`runtime preemption specifier <runtime_preemption_model>`, an optional :ref:`visibility style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>` and an optional :ref:`tls model <tls_model>`. Syntax:: - @<Name> = [Linkage] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee> + @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee> The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``, ``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers @@ -1381,6 +1411,9 @@ example: ``naked`` This attribute disables prologue / epilogue emission for the function. This can have very system-specific consequences. +``no-jump-tables`` + When this attribute is set to true, the jump tables and lookup tables that + can be generated from a switch case lowering are disabled. ``nobuiltin`` This indicates that the callee function at a call site is not recognized as a built-in function. LLVM will retain the original call and not replace it @@ -1564,6 +1597,10 @@ example: ``sanitize_thread`` This attribute indicates that ThreadSanitizer checks (dynamic thread safety analysis) are enabled for this function. +``sanitize_hwaddress`` + This attribute indicates that HWAddressSanitizer checks + (dynamic address safety analysis based on tagged pointers) are enabled for + this function. ``speculatable`` This function attribute indicates that the function does not have any effects besides calculating its result and does not have undefined behavior. @@ -1641,6 +1678,12 @@ example: If a function that has an ``sspstrong`` attribute is inlined into a function that doesn't have an ``sspstrong`` attribute, then the resulting function will have an ``sspstrong`` attribute. +``strictfp`` + This attribute indicates that the function was called from a scope that + requires strict floating point semantics. LLVM will not attempt any + optimizations that require assumptions about the floating point rounding + mode or that might alter the state of floating point status flags that + might otherwise be set or cleared by calling this function. ``"thunk"`` This attribute indicates that the function will delegate to some other function with a tail call. The prototype of a thunk should not be used for @@ -2016,8 +2059,11 @@ to the following rules: A pointer value is *based* on another pointer value according to the following rules: -- A pointer value formed from a ``getelementptr`` operation is *based* - on the second value operand of the ``getelementptr``. +- A pointer value formed from a scalar ``getelementptr`` operation is *based* on + the pointer-typed operand of the ``getelementptr``. +- The pointer in lane *l* of the result of a vector ``getelementptr`` operation + is *based* on the pointer in lane *l* of the vector-of-pointers-typed operand + of the ``getelementptr``. - The result value of a ``bitcast`` is *based* on the operand of the ``bitcast``. - A pointer value formed by an ``inttoptr`` is *based* on all pointer @@ -2230,11 +2276,11 @@ seq\_cst total orderings of other operations that are not marked Fast-Math Flags --------------- -LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`, +LLVM IR floating-point operations (:ref:`fadd <i_fadd>`, :ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`, :ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`) and :ref:`call <i_call>` -instructions have the following flags that can be set to enable -otherwise unsafe floating point transformations. +may use the following flags to enable otherwise unsafe +floating-point transformations. ``nnan`` No NaNs - Allow optimizations to assume the arguments and result are not @@ -2258,10 +2304,17 @@ otherwise unsafe floating point transformations. Allow floating-point contraction (e.g. fusing a multiply followed by an addition into a fused multiply-and-add). +``afn`` + Approximate functions - Allow substitution of approximate calculations for + functions (sin, log, sqrt, etc). See floating-point intrinsic definitions + for places where this can apply to LLVM's intrinsic math functions. + +``reassoc`` + Allow reassociation transformations for floating-point instructions. + This may dramatically change results in floating point. + ``fast`` - Fast - Allow algebraically equivalent transformations that may - dramatically change results in floating point (e.g. reassociate). This - flag implies all the others. + This flag implies all of the others. .. _uselistorder: @@ -3142,14 +3195,11 @@ that does not have side effects (e.g. load and call are not supported). The following is the syntax for constant expressions: ``trunc (CST to TYPE)`` - Truncate a constant to another type. The bit size of CST must be - larger than the bit size of TYPE. Both types must be integers. + Perform the :ref:`trunc operation <i_trunc>` on constants. ``zext (CST to TYPE)`` - Zero extend a constant to another type. The bit size of CST must be - smaller than the bit size of TYPE. Both types must be integers. + Perform the :ref:`zext operation <i_zext>` on constants. ``sext (CST to TYPE)`` - Sign extend a constant to another type. The bit size of CST must be - smaller than the bit size of TYPE. Both types must be integers. + Perform the :ref:`sext operation <i_sext>` on constants. ``fptrunc (CST to TYPE)`` Truncate a floating point constant to another floating point type. The size of CST must be larger than the size of TYPE. Both types @@ -3183,19 +3233,14 @@ The following is the syntax for constant expressions: be scalars, or vectors of the same number of elements. If the value won't fit in the floating point type, the results are undefined. ``ptrtoint (CST to TYPE)`` - Convert a pointer typed constant to the corresponding integer - constant. ``TYPE`` must be an integer type. ``CST`` must be of - pointer type. The ``CST`` value is zero extended, truncated, or - unchanged to make it fit in ``TYPE``. + Perform the :ref:`ptrtoint operation <i_ptrtoint>` on constants. ``inttoptr (CST to TYPE)`` - Convert an integer constant to a pointer constant. TYPE must be a - pointer type. CST must be of integer type. The CST value is zero - extended, truncated, or unchanged to make it fit in a pointer size. + Perform the :ref:`inttoptr operation <i_inttoptr>` on constants. This one is *really* dangerous! ``bitcast (CST to TYPE)`` - Convert a constant, CST, to another TYPE. The constraints of the - operands are the same as those for the :ref:`bitcast - instruction <i_bitcast>`. + Convert a constant, CST, to another TYPE. + The constraints of the operands are the same as those for the + :ref:`bitcast instruction <i_bitcast>`. ``addrspacecast (CST to TYPE)`` Convert a constant pointer or constant vector of pointer, CST, to another TYPE in a different address space. The constraints of the operands are the @@ -3208,9 +3253,9 @@ The following is the syntax for constant expressions: ``select (COND, VAL1, VAL2)`` Perform the :ref:`select operation <i_select>` on constants. ``icmp COND (VAL1, VAL2)`` - Performs the :ref:`icmp operation <i_icmp>` on constants. + Perform the :ref:`icmp operation <i_icmp>` on constants. ``fcmp COND (VAL1, VAL2)`` - Performs the :ref:`fcmp operation <i_fcmp>` on constants. + Perform the :ref:`fcmp operation <i_fcmp>` on constants. ``extractelement (VAL, IDX)`` Perform the :ref:`extractelement operation <i_extractelement>` on constants. @@ -4013,12 +4058,12 @@ example: !foo = !{!4, !3} -Metadata can be used as function arguments. Here ``llvm.dbg.value`` -function is using two metadata arguments: +Metadata can be used as function arguments. Here the ``llvm.dbg.value`` +intrinsic is using three metadata arguments: .. code-block:: llvm - call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) + call void @llvm.dbg.value(metadata !24, metadata !25, metadata !26) Metadata can be attached to an instruction. Here metadata ``!21`` is attached to the ``add`` instruction using the ``!dbg`` identifier: @@ -4465,7 +4510,7 @@ source variable. DIExpressions also follow this model: A DIExpression that doesn't have a trailing ``DW_OP_stack_value`` will describe an *address* when combined with a concrete location. -.. code-block:: llvm +.. code-block:: text !0 = !DIExpression(DW_OP_deref) !1 = !DIExpression(DW_OP_plus_uconst, 3) @@ -4605,13 +4650,13 @@ As a concrete example, the type descriptor graph for the following program int i; // offset 0 float f; // offset 4 }; - + struct Outer { float f; // offset 0 double d; // offset 4 struct Inner inner_a; // offset 12 }; - + void f(struct Outer* outer, struct Inner* inner, float* f, int* i, char* c) { outer->f = 0; // tag0: (OuterStructTy, FloatScalarTy, 0) outer->inner_a.i = 0; // tag1: (OuterStructTy, IntScalarTy, 12) @@ -4858,6 +4903,23 @@ Example (assuming 64-bit pointers): !0 = !{ i64 0, i64 256 } !1 = !{ i64 -1, i64 -1 } +'``callees``' Metadata +^^^^^^^^^^^^^^^^^^^^^^ + +``callees`` metadata may be attached to indirect call sites. If ``callees`` +metadata is attached to a call site, and any callee is not among the set of +functions provided by the metadata, the behavior is undefined. The intent of +this metadata is to facilitate optimizations such as indirect-call promotion. +For example, in the code below, the call instruction may only target the +``add`` or ``sub`` functions: + +.. code-block:: llvm + + %result = call i64 %binop(i64 %x, i64 %y), !callees !0 + + ... + !0 = !{i64 (i64, i64)* @add, i64 (i64, i64)* @sub} + '``unpredictable``' Metadata ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -5143,14 +5205,37 @@ the loop identifier metadata node directly: !1 = !{!1} ; an identifier for the inner loop !2 = !{!2} ; an identifier for the outer loop +'``irr_loop``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^ + +``irr_loop`` metadata may be attached to the terminator instruction of a basic +block that's an irreducible loop header (note that an irreducible loop has more +than once header basic blocks.) If ``irr_loop`` metadata is attached to the +terminator instruction of a basic block that is not really an irreducible loop +header, the behavior is undefined. The intent of this metadata is to improve the +accuracy of the block frequency propagation. For example, in the code below, the +block ``header0`` may have a loop header weight (relative to the other headers of +the irreducible loop) of 100: + +.. code-block:: llvm + + header0: + ... + br i1 %cmp, label %t1, label %t2, !irr_loop !0 + + ... + !0 = !{"loop_header_weight", i64 100} + +Irreducible loop header weights are typically based on profile data. + '``invariant.group``' Metadata ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``invariant.group`` metadata may be attached to ``load``/``store`` instructions. -The existence of the ``invariant.group`` metadata on the instruction tells -the optimizer that every ``load`` and ``store`` to the same pointer operand -within the same invariant group can be assumed to load or store the same -value (but see the ``llvm.invariant.group.barrier`` intrinsic which affects +The existence of the ``invariant.group`` metadata on the instruction tells +the optimizer that every ``load`` and ``store`` to the same pointer operand +within the same invariant group can be assumed to load or store the same +value (but see the ``llvm.invariant.group.barrier`` intrinsic which affects when two pointers are considered the same). Pointers returned by bitcast or getelementptr with only zero indices are considered the same. @@ -5163,26 +5248,26 @@ Examples: %ptr = alloca i8 store i8 42, i8* %ptr, !invariant.group !0 call void @foo(i8* %ptr) - + %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change call void @foo(i8* %ptr) %b = load i8, i8* %ptr, !invariant.group !1 ; Can't assume anything, because group changed - - %newPtr = call i8* @getPointer(i8* %ptr) + + %newPtr = call i8* @getPointer(i8* %ptr) %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr - + %unknownValue = load i8, i8* @unknownPtr store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42 - + call void @foo(i8* %ptr) %newPtr2 = call i8* @llvm.invariant.group.barrier(i8* %ptr) %d = load i8, i8* %newPtr2, !invariant.group !0 ; Can't step through invariant.group.barrier to get value of %ptr - + ... declare void @foo(i8*) declare i8* @getPointer(i8*) declare i8* @llvm.invariant.group.barrier(i8*) - + !0 = !{!"magic ptr"} !1 = !{!"other ptr"} @@ -5191,7 +5276,7 @@ another based on aliasing information. This is because invariant.group is tied to the SSA value of the pointer operand. .. code-block:: llvm - + %v = load i8, i8* %x, !invariant.group !0 ; if %x mustalias %y then we can replace the above instruction with %v = load i8, i8* %y @@ -5221,7 +5306,7 @@ It does not have any effect on non-ELF targets. Example: -.. code-block:: llvm +.. code-block:: text $a = comdat any @a = global i32 1, comdat $a @@ -6649,9 +6734,9 @@ remainder. Note that unsigned integer remainder and signed integer remainder are distinct operations; for signed integer remainder, use '``srem``'. - + Taking the remainder of a division by zero is undefined behavior. -For vectors, if any element of the divisor is zero, the operation has +For vectors, if any element of the divisor is zero, the operation has undefined behavior. Example: @@ -6703,7 +6788,7 @@ Note that signed integer remainder and unsigned integer remainder are distinct operations; for unsigned integer remainder, use '``urem``'. Taking the remainder of a division by zero is undefined behavior. -For vectors, if any element of the divisor is zero, the operation has +For vectors, if any element of the divisor is zero, the operation has undefined behavior. Overflow also leads to undefined behavior; this is a rare case, but can occur, for example, by taking the remainder of a 32-bit division of @@ -6746,10 +6831,12 @@ Both arguments must have identical types. Semantics: """""""""" -This instruction returns the *remainder* of a division. The remainder -has the same sign as the dividend. This instruction can also take any -number of :ref:`fast-math flags <fastmath>`, which are optimization hints -to enable otherwise unsafe floating point optimizations: +Return the same value as a libm '``fmod``' function but without trapping or +setting ``errno``. + +The remainder has the same sign as the dividend. This instruction can also +take any number of :ref:`fast-math flags <fastmath>`, which are optimization +hints to enable otherwise unsafe floating-point optimizations: Example: """""""" @@ -7576,7 +7663,7 @@ be reused in the cache. The code generator may select special instructions to save cache bandwidth, such as the ``MOVNT`` instruction on x86. -The optional ``!invariant.group`` metadata must reference a +The optional ``!invariant.group`` metadata must reference a single metadata name ``<index>``. See ``invariant.group`` metadata. Semantics: @@ -7650,7 +7737,7 @@ A ``fence`` instruction can also take an optional Example: """""""" -.. code-block:: llvm +.. code-block:: text fence acquire ; yields void fence syncscope("singlethread") seq_cst ; yields void @@ -7682,10 +7769,10 @@ There are three arguments to the '``cmpxchg``' instruction: an address to operate on, a value to compare to the value currently be at that address, and a new value to place at that address if the compared values are equal. The type of '<cmp>' must be an integer or pointer type whose -bit width is a power of two greater than or equal to eight and less +bit width is a power of two greater than or equal to eight and less than or equal to a target-specific size limit. '<cmp>' and '<new>' must -have the same type, and the type of '<pointer>' must be a pointer to -that type. If the ``cmpxchg`` is marked as ``volatile``, then the +have the same type, and the type of '<pointer>' must be a pointer to +that type. If the ``cmpxchg`` is marked as ``volatile``, then the optimizer is not allowed to modify the number or order of execution of this ``cmpxchg`` with other :ref:`volatile operations <volatile>`. @@ -7705,9 +7792,9 @@ Semantics: """""""""" The contents of memory at the location specified by the '``<pointer>``' operand -is read and compared to '``<cmp>``'; if the read value is the equal, the -'``<new>``' is written. The original value at the location is returned, together -with a flag indicating success (true) or failure (false). +is read and compared to '``<cmp>``'; if the values are equal, '``<new>``' is +written to the location. The original value at the location is returned, +together with a flag indicating success (true) or failure (false). If the cmpxchg operation is marked as ``weak`` then a spurious failure is permitted: the operation may not write ``<new>`` even if the comparison @@ -8039,6 +8126,8 @@ The instructions in this category are the conversion instructions (casting) which all take a single operand and a type. They perform various bit conversions on the operand. +.. _i_trunc: + '``trunc .. to``' Instruction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -8081,6 +8170,8 @@ Example: %Z = trunc i32 122 to i1 ; yields i1:false %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7> +.. _i_zext: + '``zext .. to``' Instruction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -8121,6 +8212,8 @@ Example: %Y = zext i1 true to i32 ; yields i32:1 %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> +.. _i_sext: + '``sext .. to``' Instruction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -8973,7 +9066,7 @@ This instruction requires several arguments: ``tail`` or ``musttail`` markers to the call. It is used to prevent tail call optimization from being performed on the call. -#. The optional ``fast-math flags`` marker indicates that the call has one or more +#. The optional ``fast-math flags`` marker indicates that the call has one or more :ref:`fast-math flags <fastmath>`, which are optimization hints to enable otherwise unsafe floating-point optimizations. Fast-math flags are only valid for calls that return a floating-point scalar or vector type. @@ -10138,7 +10231,7 @@ argument to specify the step of the increment. Arguments: """""""""" The first four arguments are the same as '``llvm.instrprof_increment``' -instrinsic. +intrinsic. The last argument specifies the value of the increment of the counter variable. @@ -10403,7 +10496,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10417,20 +10510,22 @@ all types however. Overview: """"""""" -The '``llvm.sqrt``' intrinsics return the square root of the specified value, -returning the same value as the libm '``sqrt``' functions would, but without -trapping or setting ``errno``. +The '``llvm.sqrt``' intrinsics return the square root of the specified value. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the square root of the operand if it is a nonnegative -floating point number. +Return the same value as a corresponding libm '``sqrt``' function but without +trapping or setting ``errno``. For types specified by IEEE-754, the result +matches a conforming libm implementation. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.powi.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10477,7 +10572,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.sin`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10496,14 +10591,16 @@ The '``llvm.sin.*``' intrinsics return the sine of the operand. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the sine of the specified operand, returning the -same values as the libm ``sin`` functions would, and handles error -conditions in the same way. +Return the same value as a corresponding libm '``sin``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.cos.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10512,7 +10609,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.cos`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10531,14 +10628,16 @@ The '``llvm.cos.*``' intrinsics return the cosine of the operand. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the cosine of the specified operand, returning the -same values as the libm ``cos`` functions would, and handles error -conditions in the same way. +Return the same value as a corresponding libm '``cos``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.pow.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10547,7 +10646,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.pow`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10567,15 +10666,16 @@ specified (positive or negative) power. Arguments: """""""""" -The second argument is a floating point power, and the first is a value -to raise to that power. +The arguments and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the first value raised to the second power, -returning the same values as the libm ``pow`` functions would, and -handles error conditions in the same way. +Return the same value as a corresponding libm '``pow``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.exp.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10584,7 +10684,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.exp`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10604,13 +10704,16 @@ value. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the same values as the libm ``exp`` functions -would, and handles error conditions in the same way. +Return the same value as a corresponding libm '``exp``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.exp2.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10619,7 +10722,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.exp2`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10639,13 +10742,16 @@ specified value. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the same values as the libm ``exp2`` functions -would, and handles error conditions in the same way. +Return the same value as a corresponding libm '``exp2``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.log.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10654,7 +10760,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.log`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10674,13 +10780,16 @@ value. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the same values as the libm ``log`` functions -would, and handles error conditions in the same way. +Return the same value as a corresponding libm '``log``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.log10.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10689,7 +10798,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.log10`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10709,13 +10818,16 @@ specified value. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the same values as the libm ``log10`` functions -would, and handles error conditions in the same way. +Return the same value as a corresponding libm '``log10``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.log2.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10724,7 +10836,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.log2`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10744,13 +10856,16 @@ value. Arguments: """""""""" -The argument and return value are floating point numbers of the same type. +The argument and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the same values as the libm ``log2`` functions -would, and handles error conditions in the same way. +Return the same value as a corresponding libm '``log2``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.fma.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -10759,7 +10874,7 @@ Syntax: """"""" This is an overloaded intrinsic. You can use ``llvm.fma`` on any -floating point or vector of floating point type. Not all targets support +floating-point or vector of floating-point type. Not all targets support all types however. :: @@ -10773,20 +10888,21 @@ all types however. Overview: """"""""" -The '``llvm.fma.*``' intrinsics perform the fused multiply-add -operation. +The '``llvm.fma.*``' intrinsics perform the fused multiply-add operation. Arguments: """""""""" -The argument and return value are floating point numbers of the same -type. +The arguments and return value are floating-point numbers of the same type. Semantics: """""""""" -This function returns the same values as the libm ``fma`` functions -would, and does not set errno. +Return the same value as a corresponding libm '``fma``' function but without +trapping or setting ``errno``. + +When specified with the fast-math-flag 'afn', the result may be approximated +using a less accurate calculation. '``llvm.fabs.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -12242,7 +12358,7 @@ Debugger Intrinsics The LLVM debugger intrinsics (which all start with ``llvm.dbg.`` prefix), are described in the `LLVM Source Level -Debugging <SourceLevelDebugging.html#format_common_intrinsics>`_ +Debugging <SourceLevelDebugging.html#format-common-intrinsics>`_ document. Exception Handling Intrinsics @@ -12250,7 +12366,7 @@ Exception Handling Intrinsics The LLVM exception handling intrinsics (which all start with ``llvm.eh.`` prefix), are described in the `LLVM Exception -Handling <ExceptionHandling.html#format_common_intrinsics>`_ document. +Handling <ExceptionHandling.html#format-common-intrinsics>`_ document. .. _int_trampoline: @@ -12707,15 +12823,18 @@ This intrinsic indicates that the memory is mutable again. Syntax: """"""" +This is an overloaded intrinsic. The memory object can belong to any address +space. The returned pointer must belong to the same address space as the +argument. :: - declare i8* @llvm.invariant.group.barrier(i8* <ptr>) + declare i8* @llvm.invariant.group.barrier.p0i8(i8* <ptr>) Overview: """"""""" -The '``llvm.invariant.group.barrier``' intrinsic can be used when an invariant +The '``llvm.invariant.group.barrier``' intrinsic can be used when an invariant established by invariant.group metadata no longer holds, to obtain a new pointer value that does not carry the invariant information. @@ -12729,7 +12848,7 @@ the pointer to the memory for which the ``invariant.group`` no longer holds. Semantics: """""""""" -Returns another pointer that aliases its argument but which is considered different +Returns another pointer that aliases its argument but which is considered different for the purposes of ``load``/``store`` ``invariant.group`` metadata. Constrained Floating Point Intrinsics @@ -12807,7 +12926,7 @@ strictly preserve the floating point exception semantics of the original code. Any FP exception that would have been raised by the original code must be raised by the transformed code, and the transformed code must not raise any FP exceptions that would not have been raised by the original code. This is the -exception behavior argument that will be used if the code being compiled reads +exception behavior argument that will be used if the code being compiled reads the FP exception status flags, but this mode can also be used with code that unmasks FP exceptions. @@ -12825,7 +12944,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.fadd(<type> <op1>, <type> <op2>, metadata <rounding mode>, metadata <exception behavior>) @@ -12862,7 +12981,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.fsub(<type> <op1>, <type> <op2>, metadata <rounding mode>, metadata <exception behavior>) @@ -12899,7 +13018,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.fmul(<type> <op1>, <type> <op2>, metadata <rounding mode>, metadata <exception behavior>) @@ -12936,7 +13055,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.fdiv(<type> <op1>, <type> <op2>, metadata <rounding mode>, metadata <exception behavior>) @@ -12973,7 +13092,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.frem(<type> <op1>, <type> <op2>, metadata <rounding mode>, metadata <exception behavior>) @@ -13002,8 +13121,43 @@ Semantics: The value produced is the floating point remainder from the division of the two value operands and has the same type as the operands. The remainder has the -same sign as the dividend. +same sign as the dividend. + +'``llvm.experimental.constrained.fma``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare <type> + @llvm.experimental.constrained.fma(<type> <op1>, <type> <op2>, <type> <op3>, + metadata <rounding mode>, + metadata <exception behavior>) + +Overview: +""""""""" + +The '``llvm.experimental.constrained.fma``' intrinsic returns the result of a +fused-multiply-add operation on its operands. + +Arguments: +"""""""""" +The first three arguments to the '``llvm.experimental.constrained.fma``' +intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector +<t_vector>` of floating point values. All arguments must have identical types. + +The fourth and fifth arguments specify the rounding mode and exception behavior +as described above. + +Semantics: +"""""""""" + +The result produced is the product of the first two operands added to the third +operand computed with infinite precision, and then rounded to the target +precision. Constrained libm-equivalent Intrinsics -------------------------------------- @@ -13027,7 +13181,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.sqrt(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13064,7 +13218,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.pow(<type> <op1>, <type> <op2>, metadata <rounding mode>, metadata <exception behavior>) @@ -13101,7 +13255,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.powi(<type> <op1>, i32 <op2>, metadata <rounding mode>, metadata <exception behavior>) @@ -13140,7 +13294,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.sin(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13176,7 +13330,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.cos(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13212,7 +13366,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.exp(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13247,7 +13401,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.exp2(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13283,7 +13437,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.log(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13319,7 +13473,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.log10(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13354,7 +13508,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.log2(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13389,7 +13543,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.rint(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13428,7 +13582,7 @@ Syntax: :: - declare <type> + declare <type> @llvm.experimental.constrained.nearbyint(<type> <op1>, metadata <rounding mode>, metadata <exception behavior>) @@ -13574,6 +13728,27 @@ with arbitrary strings. This can be useful for special purpose optimizations that want to look for these annotations. These have no other defined use; they are ignored by code generation and optimization. +'``llvm.codeview.annotation``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +This annotation emits a label at its program point and an associated +``S_ANNOTATION`` codeview record with some additional string metadata. This is +used to implement MSVC's ``__annotation`` intrinsic. It is marked +``noduplicate``, so calls to this intrinsic prevent inlining and should be +considered expensive. + +:: + + declare void @llvm.codeview.annotation(metadata) + +Arguments: +"""""""""" + +The argument should be an MDTuple containing any number of MDStrings. + '``llvm.trap``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -14101,6 +14276,36 @@ not overflow at link time under the medium code model if ``x`` is an a constant initializer folded into a function body. This intrinsic can be used to avoid the possibility of overflows when loading from such a constant. +'``llvm.sideeffect``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare void @llvm.sideeffect() inaccessiblememonly nounwind + +Overview: +""""""""" + +The ``llvm.sideeffect`` intrinsic doesn't perform any operation. Optimizers +treat it as having side effects, so it can be inserted into a loop to +indicate that the loop shouldn't be assumed to terminate (which could +potentially lead to the loop being optimized away entirely), even if it's +an infinite loop with no other side effects. + +Arguments: +"""""""""" + +None. + +Semantics: +"""""""""" + +This intrinsic actually does nothing, but optimizers must assume that it +has externally observable side effects. + Stack Map Intrinsics -------------------- @@ -14168,7 +14373,7 @@ The '``llvm.memcpy.element.unordered.atomic.*``' intrinsic copies ``len`` bytes memory from the source location to the destination location. These locations are not allowed to overlap. The memory copy is performed as a sequence of load/store operations where each access is guaranteed to be a multiple of ``element_size`` bytes wide and -aligned at an ``element_size`` boundary. +aligned at an ``element_size`` boundary. The order of the copy is unspecified. The same value may be read from the source buffer many times, but only one write is issued to the destination buffer per @@ -14243,7 +14448,7 @@ The '``llvm.memmove.element.unordered.atomic.*``' intrinsic copies ``len`` bytes of memory from the source location to the destination location. These locations are allowed to overlap. The memory copy is performed as a sequence of load/store operations where each access is guaranteed to be a multiple of ``element_size`` -bytes wide and aligned at an ``element_size`` boundary. +bytes wide and aligned at an ``element_size`` boundary. The order of the copy is unspecified. The same value may be read from the source buffer many times, but only one write is issued to the destination buffer per @@ -14318,7 +14523,7 @@ Semantics: The '``llvm.memset.element.unordered.atomic.*``' intrinsic sets the ``len`` bytes of memory starting at the destination location to the given ``value``. The memory is set with a sequence of store operations where each access is guaranteed to be a -multiple of ``element_size`` bytes wide and aligned at an ``element_size`` boundary. +multiple of ``element_size`` bytes wide and aligned at an ``element_size`` boundary. The order of the assignment is unspecified. Only one write is issued to the destination buffer per element. It is well defined to have concurrent reads and |