(``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
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 <n>``" - Numbered convention
Any calling convention may be specified by number, allowing
target-specific calling conventions to be used. Target specific
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
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\ <ExceptionHandling.html#wineh-constraints>`_),
+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
"""""""""""""
``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
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.
!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
^^^^^^^^^^^^^^^^^^^
The terminator instructions are: ':ref:`ret <i_ret>`',
':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
-':ref:`resume <i_resume>`', ':ref:`catchpad <i_catchpad>`',
-':ref:`catchendpad <i_catchendpad>`',
+':ref:`resume <i_resume>`', ':ref:`catchswitch <i_catchswitch>`',
':ref:`catchret <i_catchret>`',
-':ref:`cleanupendpad <i_cleanupendpad>`',
':ref:`cleanupret <i_cleanupret>`',
-':ref:`terminatepad <i_terminatepad>`',
and ':ref:`unreachable <i_unreachable>`'.
.. _i_ret:
resume { i8*, i32 } %exn
-.. _i_catchpad:
+.. _i_catchswitch:
-'``catchpad``' Instruction
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+'``catchswitch``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Syntax:
"""""""
::
- <resultval> = catchpad [<args>*]
- to label <normal label> unwind label <exception label>
+ <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind to caller
+ <resultval> = catchswitch within <parent> [ label <handler1>, label <handler2>, ... ] unwind label <default>
Overview:
"""""""""
-The '``catchpad``' instruction is used by `LLVM's exception handling
-system <ExceptionHandling.html#overview>`_ 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 <t_token>` and is used to match the ``catchpad`` to
-corresponding :ref:`catchrets <i_catchret>`.
+The '``catchswitch``' instruction is used by `LLVM's exception handling system
+<ExceptionHandling.html#overview>`_ to describe the set of possible catch handlers
+that may be executed by the :ref:`EH personality routine <personalityfn>`.
Arguments:
""""""""""
-The instruction takes a list of arbitrary values which are interpreted
-by the :ref:`personality function <personalityfn>`.
-
-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 <nextaction>
- catchendpad unwind to caller
-
-Overview:
-"""""""""
-
-The '``catchendpad``' instruction is used by `LLVM's exception handling
-system <ExceptionHandling.html#overview>`_ to communicate to the
-:ref:`personality function <personalityfn>` which invokes are associated
-with a chain of :ref:`catchpad <i_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 ``nextaction`` label indicates where control should transfer to if
-none of the ``catchpad`` instructions are suitable for catching the
-in-flight exception.
+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``.
-If a ``nextaction`` label is not present, the instruction unwinds out of
-its parent function. The
-:ref:`personality function <personalityfn>` will continue processing
-exception handling actions in the caller.
+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\ <ExceptionHandling.html#wineh-constraints>`_.
-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 <i_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:
::
- catchret <value> to label <normal>
+ catchret from <token> to label <normal>
Overview:
"""""""""
Semantics:
""""""""""
-The '``catchret``' instruction ends the existing (in-flight) exception
-whose unwinding was interrupted with a
-:ref:`catchpad <i_catchpad>` instruction.
-The :ref:`personality function <personalityfn>` 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 <value> unwind label <nextaction>
- cleanupendpad <value> unwind to caller
-
-Overview:
-"""""""""
-
-The '``cleanupendpad``' instruction is used by `LLVM's exception handling
-system <ExceptionHandling.html#overview>`_ to communicate to the
-:ref:`personality function <personalityfn>` which invokes are associated
-with a :ref:`cleanuppad <i_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 <personalityfn>` 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 <i_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 <i_catchpad>` instruction. The
+:ref:`personality function <personalityfn>` 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\ <ExceptionHandling.html#wineh-constraints>`_),
+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:
::
- cleanupret <value> unwind label <continue>
- cleanupret <value> unwind to caller
+ cleanupret from <value> unwind label <continue>
+ cleanupret from <value> unwind to caller
Overview:
"""""""""
The '``cleanupret``' instruction requires one argument, which indicates
which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_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\ <ExceptionHandling.html#wineh-constraints>`_),
+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\ <ExceptionHandling.html#wineh-constraints>`_.
Semantics:
""""""""""
:ref:`cleanuppad <i_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 [<args>*] unwind label <exception label>
- terminatepad [<args>*] unwind to caller
-
-Overview:
-"""""""""
-
-The '``terminatepad``' instruction is used by `LLVM's exception handling
-system <ExceptionHandling.html#overview>`_ 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 <personalityfn>`.
-
-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:
execution of this ``load`` with other :ref:`volatile
operations <volatile>`.
-If the ``load`` is marked as ``atomic``, it takes an extra
-:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
-``release`` and ``acq_rel`` orderings are not valid on ``load``
-instructions. Atomic loads produce :ref:`defined <memmodel>` 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
+<ordering>` and optional ``singlethread`` argument. The ``release`` and
+``acq_rel`` orderings are not valid on ``load`` instructions. Atomic loads
+produce :ref:`defined <memmodel>` 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
execution of this ``store`` with other :ref:`volatile
operations <volatile>`.
-If the ``store`` is marked as ``atomic``, it takes an extra
-:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
-``acquire`` and ``acq_rel`` orderings aren't valid on ``store``
-instructions. Atomic loads produce :ref:`defined <memmodel>` 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
+<ordering>` and optional ``singlethread`` argument. The ``acquire`` and
+``acq_rel`` orderings aren't valid on ``store`` instructions. Atomic loads
+produce :ref:`defined <memmodel>` 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
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
::
- <result> = [tail | musttail | notail ] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
+ <result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
[ operand bundles ]
Overview:
``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 <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.
+
#. The optional "cconv" marker indicates which :ref:`calling
convention <callingconv>` the call should use. If none is
specified, the call defaults to using C calling conventions. The
catch i8** @_ZTIi
filter [1 x i8**] [@_ZTId]
+.. _i_catchpad:
+
+'``catchpad``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <resultval> = catchpad within <catchswitch> [<args>*]
+
+Overview:
+"""""""""
+
+The '``catchpad``' instruction is used by `LLVM's exception handling
+system <ExceptionHandling.html#overview>`_ 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 <i_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 <t_token>` and is used to match the
+``catchpad`` to corresponding :ref:`catchrets <i_catchret>` 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 <i_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\ <ExceptionHandling.html#wineh>`_.
+
+When a ``catchpad`` has been "entered" but not yet "exited" (as
+described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_),
+it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>`
+that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`.
+
+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
::
- <resultval> = cleanuppad [<args>*]
+ <resultval> = cleanuppad within <parent> [<args>*]
Overview:
"""""""""
information the :ref:`personality function <personalityfn>` requires to
execute the cleanup.
The ``resultval`` has the type :ref:`token <t_token>` and is used to
-match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`
-and :ref:`cleanupendpads <i_cleanupendpad>`.
+match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`.
+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:
""""""""""
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\ <ExceptionHandling.html#wineh-constraints>`_),
+it is undefined behavior to execute a :ref:`call <i_call>` or :ref:`invoke <i_invoke>`
+that does not carry an appropriate :ref:`"funclet" bundle <ob_funclet>`.
Example:
""""""""
.. code-block:: llvm
- %tok = cleanuppad []
+ %tok = cleanuppad within %cs []
.. _intrinsics:
See the description for :ref:`llvm.stacksave <int_stacksave>`.
+.. _int_get_dynamic_area_offset:
+
+'``llvm.get.dynamic.area.offset``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i32 @llvm.get.dynamic.area.offset.i32()
+ declare i64 @llvm.get.dynamic.area.offset.i64()
+
+ Overview:
+ """""""""
+
+ The '``llvm.get.dynamic.area.offset.*``' intrinsic family is used to
+ get the offset from native stack pointer to the address of the most
+ recent dynamic alloca on the caller's stack. These intrinsics are
+ intendend for use in combination with
+ :ref:`llvm.stacksave <int_stacksave>` to get a
+ pointer to the most recent dynamic alloca. This is useful, for example,
+ for AddressSanitizer's stack unpoisoning routines.
+
+Semantics:
+""""""""""
+
+ These intrinsics return a non-negative integer value that can be used to
+ get the address of the most recent dynamic alloca, allocated by :ref:`alloca <i_alloca>`
+ on the caller's stack. In particular, for targets where stack grows downwards,
+ adding this offset to the native stack pointer would get the address of the most
+ recent dynamic alloca. For targets where stack grows upwards, the situation is a bit more
+ complicated, because substracting this value from stack pointer would get the address
+ one past the end of the most recent dynamic alloca.
+
+ Although for most targets `llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>`
+ returns just a zero, for others, such as PowerPC and PowerPC64, it returns a
+ compile-time-known constant value.
+
+ The return value type of :ref:`llvm.get.dynamic.area.offset <int_get_dynamic_area_offset>`
+ must match the target's generic address space's (address space 0) pointer type.
+
'``llvm.prefetch``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
%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
----------------------------------------