X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FLangRef.rst;h=5f8a3a5a4a9874f99b190283814d1cdb7860a98c;hb=0805780408c97128dc9164d4dbb8604882f5588e;hp=a0c23f9a213dd8d7a2463b2f25b8e7cd8e7f31d1;hpb=059bf3a3b7ba236f8f6dcda05692b3dbfe93aae7;p=oota-llvm.git diff --git a/docs/LangRef.rst b/docs/LangRef.rst index a0c23f9a213..5f8a3a5a4a9 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -1243,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 @@ -1571,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 @@ -5387,10 +5418,12 @@ 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 ``default`` argument is the label of another basic block beginning with a -"pad" instruction, one of ``cleanuppad`` or ``catchswitch``. +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\ `_. -The ``handlers`` are a list of successor blocks that each begin with a +The ``handlers`` are a nonempty list of successor blocks that each begin with a :ref:`catchpad ` instruction. Semantics: @@ -5414,81 +5447,6 @@ Example: dispatch2: %cs2 = catchswitch within %parenthandler [label %handler0] unwind label %cleanup -.. _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 `. - -Executing a ``catchpad`` instruction constitutes "entering" that pad. -The pad may then be "exited" in one of three ways: -1) explicitly via a ``catchret`` that consumes it. Executing such a ``catchret`` - is undefined behavior if any descendant pads have been entered but not yet - exited. -2) implicitly via a call (which unwinds all the way to the current function's caller), - or via a ``catchswitch`` or a ``cleanupret`` that unwinds to caller. -3) implicitly via an unwind edge whose destination EH pad isn't a descendant of - the ``catchpad``. When the ``catchpad`` is exited in this manner, it is - undefined behavior if the destination EH pad has a parent which is not an - ancestor of the ``catchpad`` being exited. - -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_catchret: '``catchret``' Instruction @@ -5525,11 +5483,10 @@ unwinding was interrupted with a :ref:`catchpad ` instruction. The code to, for example, destroy the active exception. Control then transfers to ``normal``. -The ``token`` argument must be a token produced by a dominating ``catchpad`` -instruction. The ``catchret`` destroys the physical frame established by -``catchpad``, so executing multiple returns on the same token without -re-executing the ``catchpad`` will result in undefined behavior. -See :ref:`catchpad ` for more details. +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: """""""" @@ -5563,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: """""""""" @@ -5573,13 +5538,6 @@ 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. -The unwind destination ``continue``, if present, must be an EH pad -whose parent is either ``none`` or an ancestor of the ``cleanuppad`` -being returned from. This constitutes an exceptional exit from all -ancestors of the completed ``cleanuppad``, up to but not including -the parent of ``continue``. -See :ref:`cleanuppad ` for more details. - Example: """""""" @@ -6829,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 @@ -6954,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 @@ -6980,7 +6936,7 @@ name ```` corresponding to a metadata node with one ``i32`` entry of value 1. The existence of the ``!nontemporal`` metadata on the instruction tells the optimizer and code generator that this load is not expected to be reused in the cache. The code generator may select special -instructions to save cache bandwidth, such as the MOVNT instruction on +instructions to save cache bandwidth, such as the ``MOVNT`` instruction on x86. The optional ``!invariant.group`` metadata must reference a @@ -8314,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: @@ -8371,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 @@ -8569,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 @@ -8623,21 +8652,10 @@ The ``cleanuppad`` instruction has several restrictions: - A basic block that is not a cleanup block may not include a '``cleanuppad``' instruction. -Executing a ``cleanuppad`` instruction constitutes "entering" that pad. -The pad may then be "exited" in one of three ways: -1) explicitly via a ``cleanupret`` that consumes it. Executing such a ``cleanupret`` - is undefined behavior if any descendant pads have been entered but not yet - exited. -2) implicitly via a call (which unwinds all the way to the current function's caller), - or via a ``catchswitch`` or a ``cleanupret`` that unwinds to caller. -3) implicitly via an unwind edge whose destination EH pad isn't a descendant of - the ``cleanuppad``. When the ``cleanuppad`` is exited in this manner, it is - undefined behavior if the destination EH pad has a parent which is not an - ancestor of the ``cleanuppad`` being exited. - -It is undefined behavior for the ``cleanuppad`` to exit via an unwind edge which -does not transitively unwind to the same destination as a constituent -``cleanupret``. +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: """"""""