an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`,
an optional :ref:`prologue <prologuedata>`,
an optional :ref:`personality <personalityfn>`,
+an optional list of attached :ref:`metadata <metadata>`,
an opening curly brace, a list of basic blocks, and a closing curly brace.
LLVM function declarations consist of the "``declare``" keyword, an
<ResultType> @<FunctionName> ([argument list])
[unnamed_addr] [fn Attrs] [section "name"] [comdat [($name)]]
[align N] [gc] [prefix Constant] [prologue Constant]
- [personality Constant] { ... }
+ [personality Constant] (!name !N)* { ... }
The argument list is a comma separated sequence of arguments where each
argument is of the following form:
Syntax::
- @<Name> = [Linkage] [Visibility] [DLLStorageClass] [ThreadLocal] [unnamed_addr] alias <AliaseeTy> @<Aliasee>
+ @<Name> = [Linkage] [Visibility] [DLLStorageClass] [ThreadLocal] [unnamed_addr] alias <AliaseeTy>
, <AliaseeTy>* @<Aliasee>
The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``,
``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
``convergent``
This attribute indicates that the callee is dependent on a convergent
thread execution pattern under certain parallel execution models.
- Transformations that are execution model agnostic may only move or
- tranform this call if the final location is control equivalent to its
- original position in the program, where control equivalence is defined as
- A dominates B and B post-dominates A, or vice versa.
+ Transformations that are execution model agnostic may not make the execution
+ of a convergent operation control dependent on any additional values.
``inlinehint``
This attribute indicates that the source code contained a hint that
inlining this function is desirable (such as the "inline" keyword in
This function attribute indicates that the function never returns
normally. This produces undefined behavior at runtime if the
function ever does dynamically return.
+``norecurse``
+ This function attribute indicates that the function does not call itself
+ either directly or indirectly down any possible call path. This produces
+ undefined behavior at runtime if the function ever does recurse.
``nounwind``
This function attribute indicates that the function never raises an
exception. If the function does raise an exception, its runtime
the ELF x86-64 abi, but it can be disabled for some compilation
units.
+
+.. _opbundles:
+
+Operand Bundles
+---------------
+
+Note: operand bundles are a work in progress, and they should be
+considered experimental at this time.
+
+Operand bundles are tagged sets of SSA values that can be associated
+with certain LLVM instructions (currently only ``call`` s and
+``invoke`` s). In a way they are like metadata, but dropping them is
+incorrect and will change program semantics.
+
+Syntax::
+
+ operand bundle set ::= '[' operand bundle ']'
+ operand bundle ::= tag '(' [ bundle operand ] (, bundle operand )* ')'
+ bundle operand ::= SSA value
+ tag ::= string constant
+
+Operand bundles are **not** part of a function's signature, and a
+given function may be called from multiple places with different kinds
+of operand bundles. This reflects the fact that the operand bundles
+are conceptually a part of the ``call`` (or ``invoke``), not the
+callee being dispatched to.
+
+Operand bundles are a generic mechanism intended to support
+runtime-introspection-like functionality for managed languages. While
+the exact semantics of an operand bundle depend on the bundle tag,
+there are certain limitations to how much the presence of an operand
+bundle can influence the semantics of a program. These restrictions
+are described as the semantics of an "unknown" operand bundle. As
+long as the behavior of an operand bundle is describable within these
+restrictions, LLVM does not need to have special knowledge of the
+operand bundle to not miscompile programs containing it.
+
+- The bundle operands for an unknown operand bundle escape in unknown
+ ways before control is transferred to the callee or invokee.
+- Calls and invokes with operand bundles have unknown read / write
+ effect on the heap on entry and exit (even if the call target is
+ ``readnone`` or ``readonly``), unless they're overriden with
+ callsite specific attributes.
+- An operand bundle at a call site cannot change the implementation
+ of the called function. Inter-procedural optimizations work as
+ usual as long as they take into account the first two properties.
+
+More specific types of operand bundles are described below.
+
+Deoptimization Operand Bundles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Deoptimization operand bundles are characterized by the ``"deopt``
+operand bundle tag. These operand bundles represent an alternate
+"safe" continuation for the call site they're attached to, and can be
+used by a suitable runtime to deoptimize the compiled frame at the
+specified call site. Exact details of deoptimization is out of scope
+for the language reference, but it usually involves rewriting a
+compiled frame into a set of interpreted frames.
+
+From the compiler's perspective, deoptimization operand bundles make
+the call sites they're attached to at least ``readonly``. They read
+through all of their pointer typed operands (even if they're not
+otherwise escaped) and the entire visible heap. Deoptimization
+operand bundles do not capture their operands except during
+deoptimization, in which case control will not be returned to the
+compiled frame.
+
.. _moduleasm:
Module-Level Inline Assembly
symbols get a ``_`` prefix.
* ``w``: Windows COFF prefix: Similar to Mach-O, but stdcall and fastcall
functions also get a suffix based on the frame size.
+ * ``x``: Windows x86 COFF prefix: Similar to Windows COFF, but use a ``_``
+ prefix for ``__cdecl`` functions.
``n<size1>:<size2>:<size3>...``
This specifies a set of native integer widths for the target CPU in
bits. For example, it might contain ``n32`` for 32-bit PowerPC,
**Null pointer constants**
The identifier '``null``' is recognized as a null pointer constant
and must be of :ref:`pointer type <t_pointer>`.
+**Token constants**
+ The identifier '``none``' is recognized as an empty token constant
+ and must be of :ref:`token type <t_token>`.
The one non-intuitive notation for constants is the hexadecimal form of
floating point constants. For example, the form
call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
-Metadata can be attached with an instruction. Here metadata ``!21`` is
-attached to the ``add`` instruction using the ``!dbg`` identifier:
+Metadata can be attached to an instruction. Here metadata ``!21`` is attached
+to the ``add`` instruction using the ``!dbg`` identifier:
.. code-block:: llvm
%indvar.next = add i64 %indvar, 1, !dbg !21
+Metadata can also be attached to a function definition. Here metadata ``!22``
+is attached to the ``foo`` function using the ``!dbg`` identifier:
+
+.. code-block:: llvm
+
+ define void @foo() !dbg !22 {
+ ret void
+ }
+
More information about specific metadata nodes recognized by the
optimizers and code generator is found below.
DISubprogram
""""""""""""
-``DISubprogram`` nodes represent functions from the source language. The
-``variables:`` field points at :ref:`variables <DILocalVariable>` that must be
-retained, even if their IR counterparts are optimized out of the IR. The
-``type:`` field must point at an :ref:`DISubroutineType`.
+``DISubprogram`` nodes represent functions from the source language. A
+``DISubprogram`` may be attached to a function definition using ``!dbg``
+metadata. The ``variables:`` field points at :ref:`variables <DILocalVariable>`
+that must be retained, even if their IR counterparts are optimized out of
+the IR. The ``type:`` field must point at an :ref:`DISubroutineType`.
.. code-block:: llvm
- !0 = !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1,
- file: !2, line: 7, type: !3, isLocal: true,
- isDefinition: false, scopeLine: 8, containingType: !4,
- virtuality: DW_VIRTUALITY_pure_virtual, virtualIndex: 10,
- flags: DIFlagPrototyped, isOptimized: true,
- function: void ()* @_Z3foov,
- templateParams: !5, declaration: !6, variables: !7)
+ define void @_Z3foov() !dbg !0 {
+ ...
+ }
+
+ !0 = distinct !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1,
+ file: !2, line: 7, type: !3, isLocal: true,
+ isDefinition: false, scopeLine: 8,
+ containingType: !4,
+ virtuality: DW_VIRTUALITY_pure_virtual,
+ virtualIndex: 10, flags: DIFlagPrototyped,
+ isOptimized: true, templateParams: !5,
+ declaration: !6, variables: !7)
.. _DILexicalBlock:
The ``llvm.bitsets`` global metadata is used to implement
:doc:`bitsets <BitSets>`.
+'``invariant.group``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``invariant.group`` metadata may be attached to ``load``/``store`` instructions.
+The existence of the ``invariant.group`` metadata on the instruction tells
+the optimizer that every ``load`` and ``store`` to the same pointer operand
+within the same invariant group can be assumed to load or store the same
+value (but see the ``llvm.invariant.group.barrier`` intrinsic which affects
+when two pointers are considered the same).
+
+Examples:
+
+.. code-block:: llvm
+
+ @unknownPtr = external global i8
+ ...
+ %ptr = alloca i8
+ store i8 42, i8* %ptr, !invariant.group !0
+ call void @foo(i8* %ptr)
+
+ %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change
+ call void @foo(i8* %ptr)
+ %b = load i8, i8* %ptr, !invariant.group !1 ; Can't assume anything, because group changed
+
+ %newPtr = call i8* @getPointer(i8* %ptr)
+ %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr
+
+ %unknownValue = load i8, i8* @unknownPtr
+ store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42
+
+ call void @foo(i8* %ptr)
+ %newPtr2 = call i8* @llvm.invariant.group.barrier(i8* %ptr)
+ %d = load i8, i8* %newPtr2, !invariant.group !0 ; Can't step through invariant.group.barrier to get value of %ptr
+
+ ...
+ declare void @foo(i8*)
+ declare i8* @getPointer(i8*)
+ declare i8* @llvm.invariant.group.barrier(i8*)
+
+ !0 = !{!"magic ptr"}
+ !1 = !{!"other ptr"}
+
+
+
Module Flags Metadata
=====================
::
<result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs]
- to label <normal label> unwind label <exception label>
+ [operand bundles] to label <normal label> unwind label <exception label>
Overview:
"""""""""
#. The optional :ref:`function attributes <fnattrs>` list. Only
'``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
attributes are valid here.
+#. The optional :ref:`operand bundles <opbundles>` list.
Semantics:
""""""""""
""""""""""
The first operand of an '``extractvalue``' instruction is a value of
-:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The operands are
+:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The other operands are
constant indices to specify which value to extract in a similar manner
as indices in a '``getelementptr``' instruction.
::
- <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !nonnull !<index>][, !dereferenceable !<index>][, !dereferenceable_or_null !<index>]
- <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
+ <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !invariant.group !<index>][, !nonnull !<index>][, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node>][, !align !<align_node>]
+ <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> [, !invariant.group !<index>]
!<index> = !{ i32 1 }
+ !<deref_bytes_node> = !{i64 <dereferenceable_bytes>}
+ !<align_node> = !{ i64 <value_alignment> }
Overview:
"""""""""
but it does imply that once the location is known dereferenceable
its value is henceforth unchanging.
+The optional ``!invariant.group`` metadata must reference a single metadata name
+ ``<index>`` corresponding to a metadata node. See ``invariant.group`` metadata.
+
The optional ``!nonnull`` metadata must reference a single
metadata name ``<index>`` corresponding to a metadata node with no
entries. The existence of the ``!nonnull`` metadata on the
on parameters and return values. This metadata can only be applied
to loads of a pointer type.
-The optional ``!dereferenceable`` metadata must reference a single
-metadata name ``<index>`` corresponding to a metadata node with one ``i64``
+The optional ``!dereferenceable`` metadata must reference a single metadata
+name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64``
entry. The existence of the ``!dereferenceable`` metadata on the instruction
tells the optimizer that the value loaded is known to be dereferenceable.
The number of bytes known to be dereferenceable is specified by the integer
to loads of a pointer type.
The optional ``!dereferenceable_or_null`` metadata must reference a single
-metadata name ``<index>`` corresponding to a metadata node with one ``i64``
-entry. The existence of the ``!dereferenceable_or_null`` metadata on the
+metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one
+``i64`` entry. The existence of the ``!dereferenceable_or_null`` metadata on the
instruction tells the optimizer that the value loaded is known to be either
dereferenceable or null.
The number of bytes known to be dereferenceable is specified by the integer
attribute on parameters and return values. This metadata can only be applied
to loads of a pointer type.
+The optional ``!align`` metadata must reference a single metadata name
+``<align_node>`` corresponding to a metadata node with one ``i64`` entry.
+The existence of the ``!align`` metadata on the instruction tells the
+optimizer that the value loaded is known to be aligned to a boundary specified
+by the integer value in the metadata node. The alignment must be a power of 2.
+This is analogous to the ''align'' attribute on parameters and return values.
+This metadata can only be applied to loads of a pointer type.
+
Semantics:
""""""""""
::
- store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] ; yields void
- store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> ; yields void
+ store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.group !<index>] ; yields void
+ store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> [, !invariant.group !<index>] ; yields void
Overview:
"""""""""
instructions to save cache bandwidth, such as the MOVNT instruction on
x86.
+The optional ``!invariant.group`` metadata must reference a
+single metadata name ``<index>``. See ``invariant.group`` metadata.
+
Semantics:
""""""""""
::
- <result> = [tail | musttail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
+ <result> = [tail | musttail | notail ] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
+ [ operand bundles ]
Overview:
"""""""""
- `Platform-specific constraints are
met. <CodeGenerator.html#tailcallopt>`_
+#. The optional ``notail`` marker indicates that the optimizers should not add
+ ``tail`` or ``musttail`` markers to the call. It is used to prevent tail
+ call optimization from being performed on the call.
+
#. 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
#. The optional :ref:`function attributes <fnattrs>` list. Only
'``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
attributes are valid here.
+#. The optional :ref:`operand bundles <opbundles>` list.
Semantics:
""""""""""
LLVM provides intrinsics for a few important bit manipulation
operations. These allow efficient code generation for some algorithms.
+'``llvm.bitreverse.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic function. You can use bitreverse on any
+integer type.
+
+::
+
+ declare i16 @llvm.bitreverse.i16(i16 <id>)
+ declare i32 @llvm.bitreverse.i32(i32 <id>)
+ declare i64 @llvm.bitreverse.i64(i64 <id>)
+
+Overview:
+"""""""""
+
+The '``llvm.bitreverse``' family of intrinsics is used to reverse the
+bitpattern of an integer value; for example ``0b1234567`` becomes
+``0b7654321``.
+
+Semantics:
+""""""""""
+
+The ``llvm.bitreverse.iN`` intrinsic returns an i16 value that has bit
+``M`` in the input moved to bit ``N-M`` in the output.
+
'``llvm.bswap.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Overview:
"""""""""
-The ``llvm.uabsdiff`` intrinsic returns a vector result of the absolute difference of
-the two operands, treating them both as unsigned integers.
+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.
+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
+ They are generated by compiler passes such as the Loop and SLP vectorizers. It is not
recommended for users to create them manually.
Arguments:
is equivalent to::
- %sub = sub <4 x i32> %a, %b
- %ispos = icmp ugt <4 x i32> %sub, <i32 -1, i32 -1, i32 -1, i32 -1>
- %neg = sub <4 x i32> zeroinitializer, %sub
- %1 = select <4 x i1> %ispos, <4 x i32> %sub, <4 x i32> %neg
+ %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>
-Similarly the expression::
+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 sgt <4 x i32> %sub, <i32 -1, i32 -1, i32 -1, i32 -1>
+ %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
This intrinsic indicates that the memory is mutable again.
+'``llvm.invariant.group.barrier``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.invariant.group.barrier(i8* <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.invariant.group.barrier``' intrinsic can be used when an invariant
+established by invariant.group metadata no longer holds, to obtain a new pointer
+value that does not carry the invariant information.
+
+
+Arguments:
+""""""""""
+
+The ``llvm.invariant.group.barrier`` takes only one argument, which is
+the pointer to the memory for which the ``invariant.group`` no longer holds.
+
+Semantics:
+""""""""""
+
+Returns another pointer that aliases its argument but which is considered different
+for the purposes of ``load``/``store`` ``invariant.group`` metadata.
+
General Intrinsics
------------------
projects / oota-llvm.git / blobdiff