X-Git-Url: http://plrg.eecs.uci.edu/git/?p=oota-llvm.git;a=blobdiff_plain;f=docs%2FLangRef.rst;h=5f8a3a5a4a9874f99b190283814d1cdb7860a98c;hp=09efa75515cf04b6a2f74269884438c7479e27d4;hb=6ca6b8a0c8560555aed16b880f1499a5a0b4deda;hpb=8cec2f281696a19faee58cd0749a70fbcc0fa218 diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 09efa75515c..5f8a3a5a4a9 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 @@ -1242,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 @@ -1570,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 @@ -5004,7 +5036,6 @@ The terminator instructions are: ':ref:`ret `', ':ref:`resume `', ':ref:`catchswitch `', ':ref:`catchret `', ':ref:`cleanupret `', -':ref:`terminatepad `', and ':ref:`unreachable `'. .. _i_ret: @@ -5363,7 +5394,7 @@ Example: .. _i_catchswitch: '``catchswitch``' Instruction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Syntax: """"""" @@ -5387,11 +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``, ``terminatepad``, 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: @@ -5415,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``, ``cleanupret``, or ``terminatepad`` 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 @@ -5526,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: """""""" @@ -5564,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: """""""""" @@ -5574,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: """""""" @@ -5589,62 +5546,6 @@ Example: cleanupret from %cleanup unwind to caller cleanupret from %cleanup unwind label %continue -.. _i_terminatepad: - -'``terminatepad``' Instruction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Syntax: -""""""" - -:: - - terminatepad within [*] unwind label - terminatepad within [*] 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 is both a terminator and a "pad" instruction, -meaning that is always the only non-phi instruction in the basic block. - -Example: -"""""""" - -.. code-block:: llvm - - ;; A terminate block which only permits integers. - terminatepad within none [i8** @_ZTIi] unwind label %continue - .. _i_unreachable: '``unreachable``' Instruction @@ -6886,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 @@ -7011,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 @@ -7037,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 @@ -8371,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: @@ -8428,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 @@ -8626,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 @@ -8680,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``, ``cleanupret``, or ``terminatepad`` 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: """"""""