[IR][doc] Alignment is always set in memory for load/store/alloca/cmpxchg/atomicrmw.

[gchatelet]

Summary

Context https://reviews.llvm.org/D142459#4081179

[efriedma]

The phrasing isn't grammatically correct. I would say something like:

"The alignment is only optional when parsing textual IR; for in-memory IR, it is always present."

If you want to try to rearrange the text a bit, maybe put all discussion of the "optional-ness" of the alignment into a separate paragraph from the main definition of alignment.

[gchatelet]

• Address comments

[gchatelet]

In D142625#4083421, @efriedma wrote:

The phrasing isn't grammatically correct. I would say something like:

"The alignment is only optional when parsing textual IR; for in-memory IR, it is always present."

If you want to try to rearrange the text a bit, maybe put all discussion of the "optional-ness" of the alignment into a separate paragraph from the main definition of alignment.

Thx for the suggestion. I've reworded a bit, let me know what you think.

[efriedma]

LGTM, but there's probably a merge conflict with D142633.

[gchatelet]

• Address comments

[gchatelet]

In D142625#4086606, @efriedma wrote:

LGTM, but there's probably a merge conflict with D142633.

Thx for the heads up.
I've updated the patch accordingly but there is still a reference to 0 for alloca. I suppose this should go away as well right?

[efriedma]

I suppose this should go away as well right?

Yes, I think so.

[gchatelet]

• rebase
• remove handling of the 0 value for alloca's alignement

llvm/docs/LangRef.rst

 
 Arguments:
 """"""""""
 
 The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements``
 bytes of memory on the runtime stack, returning a pointer of the
 appropriate type to the program. If "NumElements" is specified, it is
 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
-alignment may not be greater than ``1 << 32``. If not specified, or if
-zero, the target can choose to align the allocation on any convenient
-boundary compatible with the type.
+alignment may not be greater than ``1 << 32``.
+
+The alignment is only optional when parsing textual IR; for in-memory IR,
+it is always present. If not specified, or if zero, the target can choose
+to align the allocation on any convenient boundary compatible with the type.
 
 '``type``' may be any sized type.
 
 Semantics:
 """"""""""
 
 Memory is allocated; a pointer is returned. The allocated memory is
 uninitialized, and loading from uninitialized memory produces an undefined

 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). An omitted ``align``
-argument means that the operation has the ABI alignment for the target. It is
-the responsibility of the code emitter to ensure that the alignment information
-is correct. Overestimating the alignment results in undefined behavior.
-Underestimating the alignment may produce less efficient code. An alignment of 1 is
-always safe. The maximum possible alignment is ``1 << 32``. An alignment value higher
-than the size of the loaded type implies memory up to the alignment value bytes can
-be safely loaded without trapping in the default address space. Access of the high
-bytes can interfere with debugging tools, so should not be  accessed if the function
-has the ``sanitize_thread`` or ``sanitize_address`` attributes.
+operation (that is, the alignment of the memory address). It is the 
+responsibility of the code emitter to ensure that the alignment information is
+correct. Overestimating the alignment results in undefined behavior. 
+Underestimating the alignment may produce less efficient code. An alignment of
+1 is always safe. The maximum possible alignment is ``1 << 32``. An alignment 
+value higher than the size of the loaded type implies memory up to the
+alignment value bytes can be safely loaded without trapping in the default
+address space. Access of the high bytes can interfere with debugging tools, so
+should not be accessed if the function has the ``sanitize_thread`` or
+``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
 metadata name ``<nontemp_node>`` 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 x86.

 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). An omitted ``align``
-argument means that the operation has the ABI alignment for the target.
-It is the responsibility of the code emitter to ensure that the alignment
-information is correct. Overestimating the alignment results in undefined
-behavior. Underestimating the alignment may produce less efficient code.
-An alignment of 1 is always safe. The maximum possible alignment is ``1 << 32``.
-An alignment value higher than the size of the stored type implies memory
-up to the alignment value bytes can be stored to without trapping in
-the default address space. Storing to the higher bytes however may result in
-data races if another thread can access the same address. Introducing a
-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
-function has the ``sanitize_address`` attribute.
+operation (that is, the alignment of the memory address). It is the 
+responsibility of the code emitter to ensure that the alignment information is
+correct. Overestimating the alignment results in undefined behavior. 
+Underestimating the alignment may produce less efficient code. An alignment of
+1 is always safe. The maximum possible alignment is ``1 << 32``. An alignment 
+value higher than the size of the loaded type implies memory up to the
+alignment value bytes can be safely loaded without trapping in the default
+address space. Access of the high bytes can interfere with debugging tools, so
+should not be accessed if the function has the ``sanitize_thread`` or
+``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 metadata
 name ``<nontemp_node>`` 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
 x86.

 The success and failure :ref:`ordering <ordering>` arguments specify how this
 ``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters
 must be at least ``monotonic``, the failure ordering cannot be either
 ``release`` or ``acq_rel``.
 
 A ``cmpxchg`` instruction can also take an optional
 ":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
-`<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
 different from the alignment used for the load/store instructions when align
 isn't specified.
 
 The pointer passed into cmpxchg must have alignment greater than or
 equal to the size in memory of the operand.
 
 Semantics:

 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
 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
 the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not
 allowed to modify the number or order of execution of this
 ``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
-`<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
 different from the alignment used for the load/store instructions when align
 isn't specified.
 
 A ``atomicrmw`` instruction can also take an optional
 ":ref:`syncscope <syncscope>`" argument.
 
 Semantics: