X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FLangRef.rst;h=7d3f9648863ae61d2bb60d0d0426e371df78c3d4;hb=a769f56ac58b9ab9aacbd0c7198cd19272254855;hp=36bfb5167795901547171bae959dcae78570e822;hpb=2fdb3b844fe006f3b28030a5c2e99940daa74d28;p=oota-llvm.git diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 36bfb516779..7d3f9648863 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -204,14 +204,15 @@ linkage: (``STB_LOCAL`` in the case of ELF) in the object file. This corresponds to the notion of the '``static``' keyword in C. ``available_externally`` - Globals with "``available_externally``" linkage are never emitted - into the object file corresponding to the LLVM module. They exist to - allow inlining and other optimizations to take place given knowledge - of the definition of the global, which is known to be somewhere - outside the module. Globals with ``available_externally`` linkage - are allowed to be discarded at will, and are otherwise the same as - ``linkonce_odr``. This linkage type is only allowed on definitions, - not declarations. + Globals with "``available_externally``" linkage are never emitted into + the object file corresponding to the LLVM module. From the linker's + perspective, an ``available_externally`` global is equivalent to + an external declaration. They exist to allow inlining and other + optimizations to take place given knowledge of the definition of the + global, which is known to be somewhere outside the module. Globals + with ``available_externally`` linkage are allowed to be discarded at + will, and allow inlining and other optimizations. This linkage type is + only allowed on definitions, not declarations. ``linkonce`` Globals with "``linkonce``" linkage are merged with other globals of the same name when linkage occurs. This can be used to implement @@ -406,6 +407,26 @@ added in the future: This calling convention, like the `PreserveMost` calling convention, will be used by a future version of the ObjectiveC runtime and should be considered experimental at this time. +"``cxx_fast_tlscc``" - The `CXX_FAST_TLS` calling convention for access functions + Clang generates an access function to access C++-style TLS. The access + function generally has an entry block, an exit block and an initialization + block that is run at the first time. The entry and exit blocks can access + a few TLS IR variables, each access will be lowered to a platform-specific + sequence. + + This calling convention aims to minimize overhead in the caller by + preserving as many registers as possible (all the registers that are + perserved on the fast path, composed of the entry and exit blocks). + + This calling convention behaves identical to the `C` calling convention on + how arguments and return values are passed, but it uses a different set of + caller/callee-saved registers. + + Given that each platform has its own lowering sequence, hence its own set + of preserved registers, we can't use the existing `PreserveMost`. + + - On X86-64 the callee preserves all general purpose registers, except for + RDI and RAX. "``cc ``" - Numbered convention Any calling convention may be specified by number, allowing target-specific calling conventions to be used. Target specific @@ -1222,6 +1243,14 @@ example: thread execution pattern under certain parallel execution models. Transformations that are execution model agnostic may not make the execution of a convergent operation control dependent on any additional values. +``inaccessiblememonly`` + This attribute indicates that the function may only access memory that + is not accessible by the module being compiled. This is a weaker form + of ``readnone``. +``inaccessiblemem_or_argmemonly`` + This attribute indicates that the function may only access memory that is + either not accessible by the module being compiled, or is pointed to + by its pointer arguments. This is a weaker form of ``argmemonly`` ``inlinehint`` This attribute indicates that the source code contained a hint that inlining this function is desirable (such as the "inline" keyword in @@ -1550,6 +1579,29 @@ caller's deoptimization state to the callee's deoptimization state is semantically equivalent to composing the caller's deoptimization continuation after the callee's deoptimization continuation. +.. _ob_funclet: + +Funclet Operand Bundles +^^^^^^^^^^^^^^^^^^^^^^^ + +Funclet operand bundles are characterized by the ``"funclet"`` +operand bundle tag. These operand bundles indicate that a call site +is within a particular funclet. There can be at most one +``"funclet"`` operand bundle attached to a call site and it must have +exactly one bundle operand. + +If any funclet EH pads have been "entered" but not "exited" (per the +`description in the EH doc\ `_), +it is undefined behavior to execute a ``call`` or ``invoke`` which: + +* does not have a ``"funclet"`` bundle and is not a ``call`` to a nounwind + intrinsic, or +* has a ``"funclet"`` bundle whose operand is not the most-recently-entered + not-yet-exited funclet EH pad. + +Similarly, if no funclet EH pads have been entered-but-not-yet-exited, +executing a ``call`` or ``invoke`` with a ``"funclet"`` bundle is undefined behavior. + .. _moduleasm: Module-Level Inline Assembly @@ -3731,9 +3783,9 @@ DICompileUnit """"""""""""" ``DICompileUnit`` nodes represent a compile unit. The ``enums:``, -``retainedTypes:``, ``subprograms:``, ``globals:`` and ``imports:`` fields are -tuples containing the debug info to be emitted along with the compile unit, -regardless of code optimizations (some nodes are only emitted if there are +``retainedTypes:``, ``subprograms:``, ``globals:``, ``imports:`` and ``macros:`` +fields are tuples containing the debug info to be emitted along with the compile +unit, regardless of code optimizations (some nodes are only emitted if there are references to them from instructions). .. code-block:: llvm @@ -3742,7 +3794,7 @@ references to them from instructions). isOptimized: true, flags: "-O2", runtimeVersion: 2, splitDebugFilename: "abc.debug", emissionKind: 1, enums: !2, retainedTypes: !3, subprograms: !4, - globals: !5, imports: !6) + globals: !5, imports: !6, macros: !7, dwoId: 0x0abcd) Compile unit descriptors provide the root scope for objects declared in a specific compilation unit. File descriptors are defined using this scope. @@ -4108,6 +4160,32 @@ compile unit. !2 = !DIImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0, entity: !1, line: 7) +DIMacro +""""""" + +``DIMacro`` nodes represent definition or undefinition of a macro identifiers. +The ``name:`` field is the macro identifier, followed by macro parameters when +definining a function-like macro, and the ``value`` field is the token-string +used to expand the macro identifier. + +.. code-block:: llvm + + !2 = !DIMacro(macinfo: DW_MACINFO_define, line: 7, name: "foo(x)", + value: "((x) + 1)") + !3 = !DIMacro(macinfo: DW_MACINFO_undef, line: 30, name: "foo") + +DIMacroFile +""""""""""" + +``DIMacroFile`` nodes represent inclusion of source files. +The ``nodes:`` field is a list of ``DIMacro`` and ``DIMacroFile`` nodes that +appear in the included source file. + +.. code-block:: llvm + + !2 = !DIMacroFile(macinfo: DW_MACINFO_start_file, line: 7, file: !2, + nodes: !3) + '``tbaa``' Metadata ^^^^^^^^^^^^^^^^^^^ @@ -4955,12 +5033,9 @@ control flow, not values (the one exception being the The terminator instructions are: ':ref:`ret `', ':ref:`br `', ':ref:`switch `', ':ref:`indirectbr `', ':ref:`invoke `', -':ref:`resume `', ':ref:`catchpad `', -':ref:`catchendpad `', +':ref:`resume `', ':ref:`catchswitch `', ':ref:`catchret `', -':ref:`cleanupendpad `', ':ref:`cleanupret `', -':ref:`terminatepad `', and ':ref:`unreachable `'. .. _i_ret: @@ -5316,165 +5391,61 @@ Example: resume { i8*, i32 } %exn -.. _i_catchpad: +.. _i_catchswitch: -'``catchpad``' Instruction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +'``catchswitch``' Instruction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Syntax: """"""" :: - = catchpad [*] - to label unwind label + = catchswitch within [ label , label , ... ] unwind to caller + = catchswitch within [ label , label , ... ] unwind label Overview: """"""""" -The '``catchpad``' instruction is used by `LLVM's exception handling -system `_ to specify that a basic block -is a catch block --- one where a personality routine attempts to transfer -control to catch an exception. -The ``args`` correspond to whatever information the personality -routine requires to know if this is an appropriate place to catch the -exception. Control is transfered to the ``exception`` label if the -``catchpad`` is not an appropriate handler for the in-flight exception. -The ``normal`` label should contain the code found in the ``catch`` -portion of a ``try``/``catch`` sequence. The ``resultval`` has the type -:ref:`token ` and is used to match the ``catchpad`` to -corresponding :ref:`catchrets `. +The '``catchswitch``' instruction is used by `LLVM's exception handling system +`_ to describe the set of possible catch handlers +that may be executed by the :ref:`EH personality routine `. Arguments: """""""""" -The instruction takes a list of arbitrary values which are interpreted -by the :ref:`personality function `. - -The ``catchpad`` must be provided a ``normal`` label to transfer control -to if the ``catchpad`` matches the exception and an ``exception`` -label to transfer control to if it doesn't. - -Semantics: -"""""""""" - -When the call stack is being unwound due to an exception being thrown, -the exception is compared against the ``args``. If it doesn't match, -then control is transfered to the ``exception`` basic block. -As with calling conventions, how the personality function results are -represented in LLVM IR is target specific. - -The ``catchpad`` instruction has several restrictions: - -- A catch block is a basic block which is the unwind destination of - an exceptional instruction. -- A catch block must have a '``catchpad``' instruction as its - first non-PHI instruction. -- A catch block's ``exception`` edge must refer to a catch block or a - catch-end block. -- There can be only one '``catchpad``' instruction within the - catch block. -- A basic block that is not a catch block may not include a - '``catchpad``' instruction. -- A catch block which has another catch block as a predecessor may not have - any other predecessors. -- It is undefined behavior for control to transfer from a ``catchpad`` to a - ``ret`` without first executing a ``catchret`` that consumes the - ``catchpad`` or unwinding through its ``catchendpad``. -- It is undefined behavior for control to transfer from a ``catchpad`` to - itself without first executing a ``catchret`` that consumes the - ``catchpad`` or unwinding through its ``catchendpad``. - -Example: -"""""""" - -.. code-block:: llvm - - ;; A catch block which can catch an integer. - %tok = catchpad [i8** @_ZTIi] - to label %int.handler unwind label %terminate - -.. _i_catchendpad: - -'``catchendpad``' Instruction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: -""""""" - -:: - - catchendpad unwind label - catchendpad unwind to caller - -Overview: -""""""""" - -The '``catchendpad``' instruction is used by `LLVM's exception handling -system `_ to communicate to the -:ref:`personality function ` which invokes are associated -with a chain of :ref:`catchpad ` instructions; propagating an -exception out of a catch handler is represented by unwinding through its -``catchendpad``. Unwinding to the outer scope when a chain of catch handlers -do not handle an exception is also represented by unwinding through their -``catchendpad``. +The ``parent`` argument is the token of the funclet that contains the +``catchswitch`` instruction. If the ``catchswitch`` is not inside a funclet, +this operand may be the token ``none``. -The ``nextaction`` label indicates where control should transfer to if -none of the ``catchpad`` instructions are suitable for catching the -in-flight exception. +The ``default`` argument is the label of another basic block beginning with +either a ``cleanuppad`` or ``catchswitch`` instruction. This unwind destination +must be a legal target with respect to the ``parent`` links, as described in +the `exception handling documentation\ `_. -If a ``nextaction`` label is not present, the instruction unwinds out of -its parent function. The -:ref:`personality function ` will continue processing -exception handling actions in the caller. - -Arguments: -"""""""""" - -The instruction optionally takes a label, ``nextaction``, indicating -where control should transfer to if none of the preceding -``catchpad`` instructions are suitable for the in-flight exception. +The ``handlers`` are a nonempty list of successor blocks that each begin with a +:ref:`catchpad ` instruction. Semantics: """""""""" -When the call stack is being unwound due to an exception being thrown -and none of the constituent ``catchpad`` instructions match, then -control is transfered to ``nextaction`` if it is present. If it is not -present, control is transfered to the caller. +Executing this instruction transfers control to one of the successors in +``handlers``, if appropriate, or continues to unwind via the unwind label if +present. -The ``catchendpad`` instruction has several restrictions: - -- A catch-end block is a basic block which is the unwind destination of - an exceptional instruction. -- A catch-end block must have a '``catchendpad``' instruction as its - first non-PHI instruction. -- There can be only one '``catchendpad``' instruction within the - catch-end block. -- A basic block that is not a catch-end block may not include a - '``catchendpad``' instruction. -- Exactly one catch block may unwind to a ``catchendpad``. -- It is undefined behavior to execute a ``catchendpad`` if none of the - '``catchpad``'s chained to it have been executed. -- It is undefined behavior to execute a ``catchendpad`` twice without an - intervening execution of one or more of the '``catchpad``'s chained to it. -- It is undefined behavior to execute a ``catchendpad`` if, after the most - recent execution of the normal successor edge of any ``catchpad`` chained - to it, some ``catchret`` consuming that ``catchpad`` has already been - executed. -- It is undefined behavior to execute a ``catchendpad`` if, after the most - recent execution of the normal successor edge of any ``catchpad`` chained - to it, any other ``catchpad`` or ``cleanuppad`` has been executed but has - not had a corresponding - ``catchret``/``cleanupret``/``catchendpad``/``cleanupendpad`` executed. +The ``catchswitch`` is both a terminator and a "pad" instruction, meaning that +it must be both the first non-phi instruction and last instruction in the basic +block. Therefore, it must be the only non-phi instruction in the block. Example: """""""" .. code-block:: llvm - catchendpad unwind label %terminate - catchendpad unwind to caller + dispatch1: + %cs1 = catchswitch within none [label %handler0, label %handler1] unwind to caller + dispatch2: + %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup .. _i_catchret: @@ -5486,7 +5457,7 @@ Syntax: :: - catchret to label + catchret from to label Overview: """"""""" @@ -5506,105 +5477,23 @@ transfer to next. Semantics: """""""""" -The '``catchret``' instruction ends the existing (in-flight) exception -whose unwinding was interrupted with a -:ref:`catchpad ` instruction. -The :ref:`personality function ` gets a chance to execute -arbitrary code to, for example, run a C++ destructor. -Control then transfers to ``normal``. -It may be passed an optional, personality specific, value. - -It is undefined behavior to execute a ``catchret`` whose ``catchpad`` has -not been executed. - -It is undefined behavior to execute a ``catchret`` if, after the most recent -execution of its ``catchpad``, some ``catchret`` or ``catchendpad`` linked -to the same ``catchpad`` has already been executed. - -It is undefined behavior to execute a ``catchret`` if, after the most recent -execution of its ``catchpad``, any other ``catchpad`` or ``cleanuppad`` has -been executed but has not had a corresponding -``catchret``/``cleanupret``/``catchendpad``/``cleanupendpad`` executed. - -Example: -"""""""" - -.. code-block:: llvm - - catchret %catch label %continue - -.. _i_cleanupendpad: - -'``cleanupendpad``' Instruction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: -""""""" - -:: - - cleanupendpad unwind label - cleanupendpad unwind to caller - -Overview: -""""""""" - -The '``cleanupendpad``' instruction is used by `LLVM's exception handling -system `_ to communicate to the -:ref:`personality function ` which invokes are associated -with a :ref:`cleanuppad ` instructions; propagating an exception -out of a cleanup is represented by unwinding through its ``cleanupendpad``. - -The ``nextaction`` label indicates where control should unwind to next, in the -event that a cleanup is exited by means of an(other) exception being raised. - -If a ``nextaction`` label is not present, the instruction unwinds out of -its parent function. The -:ref:`personality function ` will continue processing -exception handling actions in the caller. - -Arguments: -"""""""""" - -The '``cleanupendpad``' instruction requires one argument, which indicates -which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad `. -It also has an optional successor, ``nextaction``, indicating where control -should transfer to. - -Semantics: -"""""""""" - -When and exception propagates to a ``cleanupendpad``, control is transfered to -``nextaction`` if it is present. If it is not present, control is transfered to -the caller. +The '``catchret``' instruction ends an existing (in-flight) exception whose +unwinding was interrupted with a :ref:`catchpad ` instruction. The +:ref:`personality function ` gets a chance to execute arbitrary +code to, for example, destroy the active exception. Control then transfers to +``normal``. -The ``cleanupendpad`` instruction has several restrictions: - -- A cleanup-end block is a basic block which is the unwind destination of - an exceptional instruction. -- A cleanup-end block must have a '``cleanupendpad``' instruction as its - first non-PHI instruction. -- There can be only one '``cleanupendpad``' instruction within the - cleanup-end block. -- A basic block that is not a cleanup-end block may not include a - '``cleanupendpad``' instruction. -- It is undefined behavior to execute a ``cleanupendpad`` whose ``cleanuppad`` - has not been executed. -- It is undefined behavior to execute a ``cleanupendpad`` if, after the most - recent execution of its ``cleanuppad``, some ``cleanupret`` or ``cleanupendpad`` - consuming the same ``cleanuppad`` has already been executed. -- It is undefined behavior to execute a ``cleanupendpad`` if, after the most - recent execution of its ``cleanuppad``, any other ``cleanuppad`` or - ``catchpad`` has been executed but has not had a corresponding - ``cleanupret``/``catchret``/``cleanupendpad``/``catchendpad`` executed. +The ``token`` argument must be a token produced by a ``catchpad`` instruction. +If the specified ``catchpad`` is not the most-recently-entered not-yet-exited +funclet pad (as described in the `EH documentation\ `_), +the ``catchret``'s behavior is undefined. Example: """""""" .. code-block:: llvm - cleanupendpad %cleanup unwind label %terminate - cleanupendpad %cleanup unwind to caller + catchret from %catch label %continue .. _i_cleanupret: @@ -5616,8 +5505,8 @@ Syntax: :: - cleanupret unwind label - cleanupret unwind to caller + cleanupret from unwind label + cleanupret from unwind to caller Overview: """"""""" @@ -5631,7 +5520,15 @@ Arguments: The '``cleanupret``' instruction requires one argument, which indicates which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad `. -It also has an optional successor, ``continue``. +If the specified ``cleanuppad`` is not the most-recently-entered not-yet-exited +funclet pad (as described in the `EH documentation\ `_), +the ``cleanupret``'s behavior is undefined. + +The '``cleanupret``' instruction also has an optional successor, ``continue``, +which must be the label of another basic block beginning with either a +``cleanuppad`` or ``catchswitch`` instruction. This unwind destination must +be a legal target with respect to the ``parent`` links, as described in the +`exception handling documentation\ `_. Semantics: """""""""" @@ -5641,89 +5538,13 @@ The '``cleanupret``' instruction indicates to the :ref:`cleanuppad ` it transferred control to has ended. It transfers control to ``continue`` or unwinds out of the function. -It is undefined behavior to execute a ``cleanupret`` whose ``cleanuppad`` has -not been executed. - -It is undefined behavior to execute a ``cleanupret`` if, after the most recent -execution of its ``cleanuppad``, some ``cleanupret`` or ``cleanupendpad`` -consuming the same ``cleanuppad`` has already been executed. - -It is undefined behavior to execute a ``cleanupret`` if, after the most recent -execution of its ``cleanuppad``, any other ``cleanuppad`` or ``catchpad`` has -been executed but has not had a corresponding -``cleanupret``/``catchret``/``cleanupendpad``/``catchendpad`` executed. - -Example: -"""""""" - -.. code-block:: llvm - - cleanupret %cleanup unwind to caller - cleanupret %cleanup unwind label %continue - -.. _i_terminatepad: - -'``terminatepad``' Instruction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: -""""""" - -:: - - terminatepad [*] unwind label - terminatepad [*] unwind to caller - -Overview: -""""""""" - -The '``terminatepad``' instruction is used by `LLVM's exception handling -system `_ to specify that a basic block -is a terminate block --- one where a personality routine may decide to -terminate the program. -The ``args`` correspond to whatever information the personality -routine requires to know if this is an appropriate place to terminate the -program. Control is transferred to the ``exception`` label if the -personality routine decides not to terminate the program for the -in-flight exception. - -Arguments: -"""""""""" - -The instruction takes a list of arbitrary values which are interpreted -by the :ref:`personality function `. - -The ``terminatepad`` may be given an ``exception`` label to -transfer control to if the in-flight exception matches the ``args``. - -Semantics: -"""""""""" - -When the call stack is being unwound due to an exception being thrown, -the exception is compared against the ``args``. If it matches, -then control is transfered to the ``exception`` basic block. Otherwise, -the program is terminated via personality-specific means. Typically, -the first argument to ``terminatepad`` specifies what function the -personality should defer to in order to terminate the program. - -The ``terminatepad`` instruction has several restrictions: - -- A terminate block is a basic block which is the unwind destination of - an exceptional instruction. -- A terminate block must have a '``terminatepad``' instruction as its - first non-PHI instruction. -- There can be only one '``terminatepad``' instruction within the - terminate block. -- A basic block that is not a terminate block may not include a - '``terminatepad``' instruction. - Example: """""""" .. code-block:: llvm - ;; A terminate block which only permits integers. - terminatepad [i8** @_ZTIi] unwind label %continue + cleanupret from %cleanup unwind to caller + cleanupret from %cleanup unwind label %continue .. _i_unreachable: @@ -6966,17 +6787,16 @@ then the optimizer is not allowed to modify the number or order of execution of this ``load`` with other :ref:`volatile operations `. -If the ``load`` is marked as ``atomic``, it takes an extra -:ref:`ordering ` and optional ``singlethread`` argument. The -``release`` and ``acq_rel`` orderings are not valid on ``load`` -instructions. Atomic loads produce :ref:`defined ` results -when they may see multiple atomic stores. The type of the pointee must -be an integer type whose bit width is a power of two greater than or -equal to eight and less than or equal to a target-specific size limit. -``align`` must be explicitly specified on atomic loads, and the load has -undefined behavior if the alignment is not set to a value which is at -least the size in bytes of the pointee. ``!nontemporal`` does not have -any defined semantics for atomic loads. +If the ``load`` is marked as ``atomic``, it takes an extra :ref:`ordering +` and optional ``singlethread`` argument. The ``release`` and +``acq_rel`` orderings are not valid on ``load`` instructions. Atomic loads +produce :ref:`defined ` results when they may see multiple atomic +stores. The type of the pointee must be an integer, pointer, or floating-point +type whose bit width is a power of two greater than or equal to eight and less +than or equal to a target-specific size limit. ``align`` must be explicitly +specified on atomic loads, and the load has undefined behavior if the alignment +is not set to a value which is at least the size in bytes of the +pointee. ``!nontemporal`` does not have any defined semantics for atomic loads. The optional constant ``align`` argument specifies the alignment of the operation (that is, the alignment of the memory address). A value of 0 @@ -7091,17 +6911,16 @@ then the optimizer is not allowed to modify the number or order of execution of this ``store`` with other :ref:`volatile operations `. -If the ``store`` is marked as ``atomic``, it takes an extra -:ref:`ordering ` and optional ``singlethread`` argument. The -``acquire`` and ``acq_rel`` orderings aren't valid on ``store`` -instructions. Atomic loads produce :ref:`defined ` results -when they may see multiple atomic stores. The type of the pointee must -be an integer type whose bit width is a power of two greater than or -equal to eight and less than or equal to a target-specific size limit. -``align`` must be explicitly specified on atomic stores, and the store -has undefined behavior if the alignment is not set to a value which is -at least the size in bytes of the pointee. ``!nontemporal`` does not -have any defined semantics for atomic stores. +If the ``store`` is marked as ``atomic``, it takes an extra :ref:`ordering +` and optional ``singlethread`` argument. The ``acquire`` and +``acq_rel`` orderings aren't valid on ``store`` instructions. Atomic loads +produce :ref:`defined ` results when they may see multiple atomic +stores. The type of the pointee must be an integer, pointer, or floating-point +type whose bit width is a power of two greater than or equal to eight and less +than or equal to a target-specific size limit. ``align`` must be explicitly +specified on atomic stores, and the store has undefined behavior if the +alignment is not set to a value which is at least the size in bytes of the +pointee. ``!nontemporal`` does not have any defined semantics for atomic stores. The optional constant ``align`` argument specifies the alignment of the operation (that is, the alignment of the memory address). A value of 0 @@ -8451,7 +8270,7 @@ Syntax: :: - = [tail | musttail | notail ] call [cconv] [ret attrs] [*] () [fn attrs] + = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [*] () [fn attrs] [ operand bundles ] Overview: @@ -8508,6 +8327,11 @@ 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 + :ref:`fast-math flags `, 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. + #. The optional "cconv" marker indicates which :ref:`calling convention ` the call should use. If none is specified, the call defaults to using C calling conventions. The @@ -8706,6 +8530,74 @@ Example: catch i8** @_ZTIi filter [1 x i8**] [@_ZTId] +.. _i_catchpad: + +'``catchpad``' Instruction +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + = catchpad within [*] + +Overview: +""""""""" + +The '``catchpad``' instruction is used by `LLVM's exception handling +system `_ to specify that a basic block +begins a catch handler --- one where a personality routine attempts to transfer +control to catch an exception. + +Arguments: +"""""""""" + +The ``catchswitch`` operand must always be a token produced by a +:ref:`catchswitch ` instruction in a predecessor block. This +ensures that each ``catchpad`` has exactly one predecessor block, and it always +terminates in a ``catchswitch``. + +The ``args`` correspond to whatever information the personality routine +requires to know if this is an appropriate handler for the exception. Control +will transfer to the ``catchpad`` if this is the first appropriate handler for +the exception. + +The ``resultval`` has the type :ref:`token ` and is used to match the +``catchpad`` to corresponding :ref:`catchrets ` and other nested EH +pads. + +Semantics: +"""""""""" + +When the call stack is being unwound due to an exception being thrown, the +exception is compared against the ``args``. If it doesn't match, control will +not reach the ``catchpad`` instruction. The representation of ``args`` is +entirely target and personality function-specific. + +Like the :ref:`landingpad ` instruction, the ``catchpad`` +instruction must be the first non-phi of its parent basic block. + +The meaning of the tokens produced and consumed by ``catchpad`` and other "pad" +instructions is described in the +`Windows exception handling documentation\ `_. + +When a ``catchpad`` has been "entered" but not yet "exited" (as +described in the `EH documentation\ `_), +it is undefined behavior to execute a :ref:`call ` or :ref:`invoke ` +that does not carry an appropriate :ref:`"funclet" bundle `. + +Example: +"""""""" + +.. code-block:: llvm + + dispatch: + %cs = catchswitch within none [label %handler0] unwind to caller + ;; A catch block which can catch an integer. + handler0: + %tok = catchpad within %cs [i8** @_ZTIi] + .. _i_cleanuppad: '``cleanuppad``' Instruction @@ -8716,7 +8608,7 @@ Syntax: :: - = cleanuppad [*] + = cleanuppad within [*] Overview: """"""""" @@ -8729,8 +8621,10 @@ The ``args`` correspond to whatever additional information the :ref:`personality function ` requires to execute the cleanup. The ``resultval`` has the type :ref:`token ` and is used to -match the ``cleanuppad`` to corresponding :ref:`cleanuprets ` -and :ref:`cleanupendpads `. +match the ``cleanuppad`` to corresponding :ref:`cleanuprets `. +The ``parent`` argument is the token of the funclet that contains the +``cleanuppad`` instruction. If the ``cleanuppad`` is not inside a funclet, +this operand may be the token ``none``. Arguments: """""""""" @@ -8757,21 +8651,18 @@ The ``cleanuppad`` instruction has several restrictions: cleanup block. - A basic block that is not a cleanup block may not include a '``cleanuppad``' instruction. -- All '``cleanupret``'s and '``cleanupendpad``'s which consume a ``cleanuppad`` - must have the same exceptional successor. -- It is undefined behavior for control to transfer from a ``cleanuppad`` to a - ``ret`` without first executing a ``cleanupret`` or ``cleanupendpad`` that - consumes the ``cleanuppad``. -- It is undefined behavior for control to transfer from a ``cleanuppad`` to - itself without first executing a ``cleanupret`` or ``cleanupendpad`` that - consumes the ``cleanuppad``. + +When a ``cleanuppad`` has been "entered" but not yet "exited" (as +described in the `EH documentation\ `_), +it is undefined behavior to execute a :ref:`call ` or :ref:`invoke ` +that does not carry an appropriate :ref:`"funclet" bundle `. Example: """""""" .. code-block:: llvm - %tok = cleanuppad [] + %tok = cleanuppad within %cs [] .. _intrinsics: @@ -9340,7 +9231,7 @@ See the description for :ref:`llvm.stacksave `. .. _int_get_dynamic_area_offset: '``llvm.get.dynamic.area.offset``' Intrinsic -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Syntax: """"""" @@ -11171,68 +11062,6 @@ Examples: %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c - -'``llvm.uabsdiff.*``' and '``llvm.sabsdiff.*``' Intrinsics -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: -""""""" -This is an overloaded intrinsic. The loaded data is a vector of any integer bit width. - -.. code-block:: llvm - - declare <4 x integer> @llvm.uabsdiff.v4i32(<4 x integer> %a, <4 x integer> %b) - - -Overview: -""""""""" - -The ``llvm.uabsdiff`` intrinsic returns a vector result of the absolute difference -of the two operands, treating them both as unsigned integers. The intermediate -calculations are computed using infinitely precise unsigned arithmetic. The final -result will be truncated to the given type. - -The ``llvm.sabsdiff`` intrinsic returns a vector result of the absolute difference of -the two operands, treating them both as signed integers. If the result overflows, the -behavior is undefined. - -.. note:: - - These intrinsics are primarily used during the code generation stage of compilation. - They are generated by compiler passes such as the Loop and SLP vectorizers. It is not - recommended for users to create them manually. - -Arguments: -"""""""""" - -Both intrinsics take two integer of the same bitwidth. - -Semantics: -"""""""""" - -The expression:: - - call <4 x i32> @llvm.uabsdiff.v4i32(<4 x i32> %a, <4 x i32> %b) - -is equivalent to:: - - %1 = zext <4 x i32> %a to <4 x i64> - %2 = zext <4 x i32> %b to <4 x i64> - %sub = sub <4 x i64> %1, %2 - %trunc = trunc <4 x i64> to <4 x i32> - -and the expression:: - - call <4 x i32> @llvm.sabsdiff.v4i32(<4 x i32> %a, <4 x i32> %b) - -is equivalent to:: - - %sub = sub nsw <4 x i32> %a, %b - %ispos = icmp sge <4 x i32> %sub, zeroinitializer - %neg = sub nsw <4 x i32> zeroinitializer, %sub - %1 = select <4 x i1> %ispos, <4 x i32> %sub, <4 x i32> %neg - - Half Precision Floating Point Intrinsics ----------------------------------------