Page MenuHomePhabricator

Please use GitHub pull requests for new patches. Phabricator shutdown timeline

Differential D142625 Diff 493507 llvm/docs/LangRef.rst

Changeset View

Standalone View

View Options

llvm/docs/LangRef.rst

  • This file is larger than 256 KB, so syntax highlighting is disabled by default.
Show First 20 Lines • Show All 10,071 Lines • ▼ Show 20 Lines
Arguments: Arguments:
"""""""""" """"""""""
The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements`` The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements``
bytes of memory on the runtime stack, returning a pointer of the bytes of memory on the runtime stack, returning a pointer of the
appropriate type to the program. If "NumElements" is specified, it is appropriate type to the program. If "NumElements" is specified, it is
the number of elements allocated, otherwise "NumElements" is defaulted the number of elements allocated, otherwise "NumElements" is defaulted
to be one. If a constant alignment is specified, the value result of the to be one.
If a constant alignment is specified, the value result of the
allocation is guaranteed to be aligned to at least that boundary. The allocation is guaranteed to be aligned to at least that boundary. The
alignment may not be greater than ``1 << 32``. If not specified, or if alignment may not be greater than ``1 << 32``.
zero, the target can choose to align the allocation on any convenient
boundary compatible with the type. The alignment is only optional when parsing textual IR; for in-memory IR,
it is always present. If not specified, the target can choose to align the
allocation on any convenient boundary compatible with the type.
'``type``' may be any sized type. '``type``' may be any sized type.
Semantics: Semantics:
"""""""""" """"""""""
Memory is allocated; a pointer is returned. The allocated memory is Memory is allocated; a pointer is returned. The allocated memory is
uninitialized, and loading from uninitialized memory produces an undefined uninitialized, and loading from uninitialized memory produces an undefined
▲ Show 20 Lines • Show All 65 Lines • ▼ Show 20 Lines
multiple atomic stores. The type of the pointee must be an integer, pointer, or 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 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 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 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 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. pointee. ``!nontemporal`` does not have any defined semantics for atomic loads.
The optional constant ``align`` argument specifies the alignment of the The optional constant ``align`` argument specifies the alignment of the
operation (that is, the alignment of the memory address). An omitted ``align`` operation (that is, the alignment of the memory address). It is the
argument means that the operation has the ABI alignment for the target. It is responsibility of the code emitter to ensure that the alignment information is
the responsibility of the code emitter to ensure that the alignment information correct. Overestimating the alignment results in undefined behavior.
is correct. Overestimating the alignment results in undefined behavior. Underestimating the alignment may produce less efficient code. An alignment of
Underestimating the alignment may produce less efficient code. An alignment of 1 is 1 is always safe. The maximum possible alignment is ``1 << 32``. An alignment
always safe. The maximum possible alignment is ``1 << 32``. An alignment value higher value higher than the size of the loaded type implies memory up to the
than the size of the loaded type implies memory up to the alignment value bytes can alignment value bytes can be safely loaded without trapping in the default
be safely loaded without trapping in the default address space. Access of the high address space. Access of the high bytes can interfere with debugging tools, so
bytes can interfere with debugging tools, so should not be accessed if the function should not be accessed if the function has the ``sanitize_thread`` or
has the ``sanitize_thread`` or ``sanitize_address`` attributes. ``sanitize_address`` attributes.
The alignment is only optional when parsing textual IR; for in-memory IR, it is
always present. An omitted ``align`` argument means that the operation has the
ABI alignment for the target.
The optional ``!nontemporal`` metadata must reference a single The optional ``!nontemporal`` metadata must reference a single
metadata name ``<nontemp_node>`` corresponding to a metadata node with one metadata name ``<nontemp_node>`` corresponding to a metadata node with one
``i32`` entry of value 1. The existence of the ``!nontemporal`` ``i32`` entry of value 1. The existence of the ``!nontemporal``
metadata on the instruction tells the optimizer and code generator metadata on the instruction tells the optimizer and code generator
that this load is not expected to be reused in the cache. The code that this load is not expected to be reused in the cache. The code
generator may select special instructions to save cache bandwidth, such generator may select special instructions to save cache bandwidth, such
as the ``MOVNT`` instruction on x86. as the ``MOVNT`` instruction on x86.
▲ Show 20 Lines • Show All 110 Lines • ▼ Show 20 Lines
multiple atomic stores. The type of the pointee must be an integer, pointer, or 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 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 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 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 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. pointee. ``!nontemporal`` does not have any defined semantics for atomic stores.
The optional constant ``align`` argument specifies the alignment of the The optional constant ``align`` argument specifies the alignment of the
operation (that is, the alignment of the memory address). An omitted ``align`` operation (that is, the alignment of the memory address). It is the
argument means that the operation has the ABI alignment for the target. responsibility of the code emitter to ensure that the alignment information is
It is the responsibility of the code emitter to ensure that the alignment correct. Overestimating the alignment results in undefined behavior.
information is correct. Overestimating the alignment results in undefined Underestimating the alignment may produce less efficient code. An alignment of
behavior. Underestimating the alignment may produce less efficient code. 1 is always safe. The maximum possible alignment is ``1 << 32``. An alignment
An alignment of 1 is always safe. The maximum possible alignment is ``1 << 32``. value higher than the size of the loaded type implies memory up to the
An alignment value higher than the size of the stored type implies memory alignment value bytes can be safely loaded without trapping in the default
up to the alignment value bytes can be stored to without trapping in address space. Access of the high bytes can interfere with debugging tools, so
the default address space. Storing to the higher bytes however may result in should not be accessed if the function has the ``sanitize_thread`` or
data races if another thread can access the same address. Introducing a ``sanitize_address`` attributes.
data race is not allowed. Storing to the extra bytes is not allowed
even in situations where a data race is known to not exist if the The alignment is only optional when parsing textual IR; for in-memory IR, it is
function has the ``sanitize_address`` attribute. always present. An omitted ``align`` argument means that the operation has the
ABI alignment for the target.
The optional ``!nontemporal`` metadata must reference a single metadata The optional ``!nontemporal`` metadata must reference a single metadata
name ``<nontemp_node>`` corresponding to a metadata node with one ``i32`` entry name ``<nontemp_node>`` corresponding to a metadata node with one ``i32`` entry
of value 1. The existence of the ``!nontemporal`` metadata on the instruction 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 tells the optimizer and code generator that this load is not expected to
be reused in the cache. The code generator may select special 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. x86.
▲ Show 20 Lines • Show All 117 Lines • ▼ Show 20 Lines
The success and failure :ref:`ordering <ordering>` arguments specify how this The success and failure :ref:`ordering <ordering>` arguments specify how this
``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters ``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters
must be at least ``monotonic``, the failure ordering cannot be either must be at least ``monotonic``, the failure ordering cannot be either
``release`` or ``acq_rel``. ``release`` or ``acq_rel``.
A ``cmpxchg`` instruction can also take an optional A ``cmpxchg`` instruction can also take an optional
":ref:`syncscope <syncscope>`" argument. ":ref:`syncscope <syncscope>`" argument.
The instruction can take an optional ``align`` attribute.
The alignment must be a power of two greater or equal to the size of the The alignment must be a power of two greater or equal to the size of the
`<value>` type. If unspecified, the alignment is assumed to be equal to the `<value>` type.
The alignment is only optional when parsing textual IR; for in-memory IR, it is
always present. If unspecified, the alignment is assumed to be equal to the
size of the '<value>' type. Note that this default alignment assumption is size of the '<value>' type. Note that this default alignment assumption is
different from the alignment used for the load/store instructions when align different from the alignment used for the load/store instructions when align
isn't specified. isn't specified.
The pointer passed into cmpxchg must have alignment greater than or The pointer passed into cmpxchg must have alignment greater than or
equal to the size in memory of the operand. equal to the size in memory of the operand.
Semantics: Semantics:
▲ Show 20 Lines • Show All 82 Lines • ▼ Show 20 Lines
and less than or equal to a target-specific size limit. For xchg, this and less than or equal to a target-specific size limit. For xchg, this
may also be a floating point or a pointer type with the same size constraints may also be a floating point or a pointer type with the same size constraints
as integers. For fadd/fsub/fmax/fmin, this must be a floating point type. The as integers. For fadd/fsub/fmax/fmin, this must be a floating point type. The
type of the '``<pointer>``' operand must be a pointer to that type. If type of the '``<pointer>``' operand must be a pointer to that type. If
the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not
allowed to modify the number or order of execution of this allowed to modify the number or order of execution of this
``atomicrmw`` with other :ref:`volatile operations <volatile>`. ``atomicrmw`` with other :ref:`volatile operations <volatile>`.
The instruction can take an optional ``align`` attribute.
The alignment must be a power of two greater or equal to the size of the The alignment must be a power of two greater or equal to the size of the
`<value>` type. If unspecified, the alignment is assumed to be equal to the `<value>` type.
The alignment is only optional when parsing textual IR; for in-memory IR, it is
always present. If unspecified, the alignment is assumed to be equal to the
size of the '<value>' type. Note that this default alignment assumption is size of the '<value>' type. Note that this default alignment assumption is
different from the alignment used for the load/store instructions when align different from the alignment used for the load/store instructions when align
isn't specified. isn't specified.
A ``atomicrmw`` instruction can also take an optional A ``atomicrmw`` instruction can also take an optional
":ref:`syncscope <syncscope>`" argument. ":ref:`syncscope <syncscope>`" argument.
Semantics: Semantics:
▲ Show 20 Lines • Show All 16,137 Lines • Show Last 20 Lines