}
; Named metadata
- !0 = metadata !{i32 42, null, metadata !"string"}
+ !0 = !{i32 42, null, !"string"}
!foo = !{!0}
This example is made up of a :ref:`global variable <globalvars>` named
Syntax::
; Some unnamed metadata nodes, which are referenced by the named metadata.
- !0 = metadata !{metadata !"zero"}
- !1 = metadata !{metadata !"one"}
- !2 = metadata !{metadata !"two"}
+ !0 = !{!"zero"}
+ !1 = !{!"one"}
+ !2 = !{!"two"}
; A named metadata.
!name = !{!0, !1, !2}
having to print large zero initializers (e.g. for large arrays) and
is always exactly equivalent to using explicit zero initializers.
**Metadata node**
- A metadata node is a structure-like constant with :ref:`metadata
- type <t_metadata>`. For example:
- "``metadata !{ i32 0, metadata !"test" }``". Unlike other
- constants that are meant to be interpreted as part of the
- instruction stream, metadata is a place to attach additional
+ A metadata node is a constant tuple without types. For example:
+ "``!{!0, !{!2, !0}, !"test"}``". Metadata can reference constant values,
+ for example: "``!{!0, i32 0, i8* @global, i64 (i64)* @function, !"str"}``".
+ Unlike other typed constants that are meant to be interpreted as part of
+ the instruction stream, metadata is a place to attach additional
information such as debug info.
Global Variable and Function Addresses
.. _metadata:
-Metadata Nodes and Metadata Strings
------------------------------------
+Metadata
+========
LLVM IR allows metadata to be attached to instructions in the program
that can convey extra information about the code to the optimizers and
code generator. One example application of metadata is source-level
debug information. There are two metadata primitives: strings and nodes.
-All metadata has the ``metadata`` type and is identified in syntax by a
-preceding exclamation point ('``!``').
+
+Metadata does not have a type, and is not a value. If referenced from a
+``call`` instruction, it uses the ``metadata`` type.
+
+All metadata are identified in syntax by a exclamation point ('``!``').
+
+Metadata Nodes and Metadata Strings
+-----------------------------------
A metadata string is a string surrounded by double quotes. It can
contain any character by escaping non-printable characters with
.. code-block:: llvm
- !{ metadata !"test\00", i32 10}
+ !{ !"test\00", i32 10}
A :ref:`named metadata <namedmetadatastructure>` is a collection of
metadata nodes, which can be looked up in the module symbol table. For
.. code-block:: llvm
- !foo = metadata !{!4, !3}
+ !foo = !{!4, !3}
Metadata can be used as function arguments. Here ``llvm.dbg.value``
function is using two metadata arguments:
.. code-block:: llvm
- !0 = metadata !{ metadata !"an example type tree" }
- !1 = metadata !{ metadata !"int", metadata !0 }
- !2 = metadata !{ metadata !"float", metadata !0 }
- !3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
+ !0 = !{ !"an example type tree" }
+ !1 = !{ !"int", !0 }
+ !2 = !{ !"float", !0 }
+ !3 = !{ !"const float", !2, i64 1 }
The first field is an identity field. It can be any value, usually a
metadata string, which uniquely identifies the type. The most important
.. code-block:: llvm
- !4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }
+ !4 = !{ i64 0, i64 4, !1, i64 8, i64 4, !2 }
This describes a struct with two fields. The first is at offset 0 bytes
with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
.. code-block:: llvm
; Two scope domains:
- !0 = metadata !{metadata !0}
- !1 = metadata !{metadata !1}
+ !0 = !{!0}
+ !1 = !{!1}
; Some scopes in these domains:
- !2 = metadata !{metadata !2, metadata !0}
- !3 = metadata !{metadata !3, metadata !0}
- !4 = metadata !{metadata !4, metadata !1}
+ !2 = !{!2, !0}
+ !3 = !{!3, !0}
+ !4 = !{!4, !1}
; Some scope lists:
- !5 = metadata !{metadata !4} ; A list containing only scope !4
- !6 = metadata !{metadata !4, metadata !3, metadata !2}
- !7 = metadata !{metadata !3}
+ !5 = !{!4} ; A list containing only scope !4
+ !6 = !{!4, !3, !2}
+ !7 = !{!3}
; These two instructions don't alias:
%0 = load float* %c, align 4, !alias.scope !5
.. code-block:: llvm
- !0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
+ !0 = !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
'``range``' Metadata
^^^^^^^^^^^^^^^^^^^^
%d = invoke i8 @bar() to label %cont
unwind label %lpad, !range !3 ; Can only be -2, -1, 3, 4 or 5
...
- !0 = metadata !{ i8 0, i8 2 }
- !1 = metadata !{ i8 255, i8 2 }
- !2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
- !3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
+ !0 = !{ i8 0, i8 2 }
+ !1 = !{ i8 255, i8 2 }
+ !2 = !{ i8 0, i8 2, i8 3, i8 6 }
+ !3 = !{ i8 -2, i8 0, i8 3, i8 6 }
'``llvm.loop``'
^^^^^^^^^^^^^^^
.. code-block:: llvm
- !0 = metadata !{ metadata !0 }
- !1 = metadata !{ metadata !1 }
+ !0 = !{!0}
+ !1 = !{!1}
The loop identifier metadata can be used to specify additional
per-loop metadata. Any operands after the first operand can be treated
br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
...
- !0 = metadata !{ metadata !0, metadata !1 }
- !1 = metadata !{ metadata !"llvm.loop.unroll.count", i32 4 }
+ !0 = !{!0, !1}
+ !1 = !{!"llvm.loop.unroll.count", i32 4}
'``llvm.loop.vectorize``' and '``llvm.loop.interleave``'
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: llvm
- !0 = metadata !{ metadata !"llvm.loop.interleave.count", i32 4 }
+ !0 = !{!"llvm.loop.interleave.count", i32 4}
Note that setting ``llvm.loop.interleave.count`` to 1 disables interleaving
multiple iterations of the loop. If ``llvm.loop.interleave.count`` is set to 0
.. code-block:: llvm
- !0 = metadata !{ metadata !"llvm.loop.vectorize.enable", i1 0 }
- !1 = metadata !{ metadata !"llvm.loop.vectorize.enable", i1 1 }
+ !0 = !{!"llvm.loop.vectorize.enable", i1 0}
+ !1 = !{!"llvm.loop.vectorize.enable", i1 1}
'``llvm.loop.vectorize.width``' Metadata
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: llvm
- !0 = metadata !{ metadata !"llvm.loop.vectorize.width", i32 4 }
+ !0 = !{!"llvm.loop.vectorize.width", i32 4}
Note that setting ``llvm.loop.vectorize.width`` to 1 disables
vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to
.. code-block:: llvm
- !0 = metadata !{ metadata !"llvm.loop.unroll.count", i32 4 }
+ !0 = !{!"llvm.loop.unroll.count", i32 4}
If the trip count of the loop is less than the unroll count the loop
will be partially unrolled.
.. code-block:: llvm
- !0 = metadata !{ metadata !"llvm.loop.unroll.disable" }
+ !0 = !{!"llvm.loop.unroll.disable"}
'``llvm.loop.unroll.full``' Metadata
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: llvm
- !0 = metadata !{ metadata !"llvm.loop.unroll.full" }
+ !0 = !{!"llvm.loop.unroll.full"}
'``llvm.mem``'
^^^^^^^^^^^^^^^
for.end:
...
- !0 = metadata !{ metadata !0 }
+ !0 = !{!0}
It is also possible to have nested parallel loops. In that case the
memory accesses refer to a list of loop identifier metadata nodes instead of
outer.for.end: ; preds = %for.body
...
- !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers
- !1 = metadata !{ metadata !1 } ; an identifier for the inner loop
- !2 = metadata !{ metadata !2 } ; an identifier for the outer loop
+ !0 = !{!1, !2} ; a list of loop identifiers
+ !1 = !{!1} ; an identifier for the inner loop
+ !2 = !{!2} ; an identifier for the outer loop
Module Flags Metadata
=====================
.. code-block:: llvm
- !0 = metadata !{ i32 1, metadata !"foo", i32 1 }
- !1 = metadata !{ i32 4, metadata !"bar", i32 37 }
- !2 = metadata !{ i32 2, metadata !"qux", i32 42 }
- !3 = metadata !{ i32 3, metadata !"qux",
- metadata !{
- metadata !"foo", i32 1
+ !0 = !{ i32 1, !"foo", i32 1 }
+ !1 = !{ i32 4, !"bar", i32 37 }
+ !2 = !{ i32 2, !"qux", i32 42 }
+ !3 = !{ i32 3, !"qux",
+ !{
+ !"foo", i32 1
}
}
!llvm.module.flags = !{ !0, !1, !2, !3 }
::
- metadata !{ metadata !"foo", i32 1 }
+ !{ !"foo", i32 1 }
The behavior is to emit an error if the ``llvm.module.flags`` does not
contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
linker options, presumably to link against ``libz`` and the ``Cocoa``
framework::
- !0 = metadata !{ i32 6, metadata !"Linker Options",
- metadata !{
- metadata !{ metadata !"-lz" },
- metadata !{ metadata !"-framework", metadata !"Cocoa" } } }
+ !0 = !{ i32 6, !"Linker Options",
+ !{
+ !{ !"-lz" },
+ !{ !"-framework", !"Cocoa" } } }
!llvm.module.flags = !{ !0 }
The metadata encoding as lists of lists of options, as opposed to a collapsed
enum is the smallest type which can represent all of its values::
!llvm.module.flags = !{!0, !1}
- !0 = metadata !{i32 1, metadata !"short_wchar", i32 1}
- !1 = metadata !{i32 1, metadata !"short_enum", i32 0}
+ !0 = !{i32 1, !"short_wchar", i32 1}
+ !1 = !{i32 1, !"short_enum", i32 0}
.. _intrinsicglobalvariables:
declare i64 @llvm.read_register.i64(metadata)
declare void @llvm.write_register.i32(metadata, i32 @value)
declare void @llvm.write_register.i64(metadata, i64 @value)
- !0 = metadata !{metadata !"sp\00"}
+ !0 = !{!"sp\00"}
Overview:
"""""""""
after performing the required machine specific adjustments. The pointer
returned can then be :ref:`bitcast and executed <int_trampoline>`.
+Masked Vector Load and Store Intrinsics
+---------------------------------------
+
+LLVM provides intrinsics for predicated vector load and store operations. The predicate is specified by a mask operand, which holds one bit per vector element, switching the associated vector lane on or off. The memory addresses corresponding to the "off" lanes are not accessed. When all bits of the mask are on, the intrinsic is identical to a regular vector load or store. When all bits are off, no memory is accessed.
+
+.. _int_mload:
+
+'``llvm.masked.load.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+This is an overloaded intrinsic. The loaded data is a vector of any integer or floating point data type.
+
+::
+
+ declare <16 x float> @llvm.masked.load.v16f32 (<16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>)
+ declare <2 x double> @llvm.masked.load.v2f64 (<2 x double>* <ptr>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>)
+
+Overview:
+"""""""""
+
+Reads a vector from memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. The masked-off lanes in the result vector are taken from the corresponding lanes in the passthru operand.
+
+
+Arguments:
+""""""""""
+
+The first operand is the base pointer for the load. The second operand is the alignment of the source location. It must be a constant integer value. The third operand, mask, is a vector of boolean 'i1' values with the same number of elements as the return type. The fourth is a pass-through value that is used to fill the masked-off lanes of the result. The return type, underlying type of the base pointer and the type of passthru operand are the same vector types.
+
+
+Semantics:
+""""""""""
+
+The '``llvm.masked.load``' intrinsic is designed for conditional reading of selected vector elements in a single IR operation. It is useful for targets that support vector masked loads and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar load operations.
+The result of this operation is equivalent to a regular vector load instruction followed by a 'select' between the loaded and the passthru values, predicated on the same mask. However, using this intrinsic prevents exceptions on memory access to masked-off lanes.
+
+
+::
+
+ %res = call <16 x float> @llvm.masked.load.v16f32 (<16 x float>* %ptr, i32 4, <16 x i1>%mask, <16 x float> %passthru)
+
+ ;; The result of the two following instructions is identical aside from potential memory access exception
+ %loadlal = load <16 x float>* %ptr, align 4
+ %res = select <16 x i1> %Mask, <16 x float> %loadlal, <16 x float> %passthru
+
+.. _int_mstore:
+
+'``llvm.masked.store.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+This is an overloaded intrinsic. The data stored in memory is a vector of any integer or floating point data type.
+
+::
+
+ declare void @llvm.masked.store.v8i32 (<8 x i32> <value>, <8 x i32> * <ptr>, i32 <alignment>, <8 x i1> <mask>)
+ declare void @llvm.masked.store.v16f32(<16 x i32> <value>, <16 x i32>* <ptr>, i32 <alignment>, <16 x i1> <mask>)
+
+Overview:
+"""""""""
+
+Writes a vector to memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes.
+
+Arguments:
+""""""""""
+
+The first operand is the vector value to be written to memory. The second operand is the base pointer for the store, it has the same underlying type as the value operand. The third operand is the alignment of the destination location. The fourth operand, mask, is a vector of boolean values. The types of the mask and the value operand must have the same number of vector elements.
+
+
+Semantics:
+""""""""""
+
+The '``llvm.masked.store``' intrinsics is designed for conditional writing of selected vector elements in a single IR operation. It is useful for targets that support vector masked store and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
+The result of this operation is equivalent to a load-modify-store sequence. However, using this intrinsic prevents exceptions and data races on memory access to masked-off lanes.
+
+::
+
+ call void @llvm.masked.store.v16f32(<16 x float> %value, <16 x float>* %ptr, i32 4, <16 x i1> %mask)
+
+ ;; The result of the following instructions is identcal aside from potential data races and memory access exceptions
+ %oldval = load <16 x float>* %ptr, align 4
+ %res = select <16 x i1> %mask, <16 x float> %value, <16 x float> %oldval
+ store <16 x float> %res, <16 x float>* %ptr, align 4
+
+
Memory Use Markers
------------------
projects / oota-llvm.git / blobdiff