Skip to content

Commit f94adfd

Browse files
authored
[docs] Reword the alignment implications for atomic instructions. (#75871)
Atomic instructions (load / store/ atomicrwm / cmpxchg) are not really undefined behavior if they lack natural alignment. They will (with AtomicExpand pass enabled) be converted into libcalls. Update the language reference to reflect this.
1 parent 7e4c6f6 commit f94adfd

File tree

1 file changed

+14
-10
lines changed

1 file changed

+14
-10
lines changed

llvm/docs/LangRef.rst

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10515,9 +10515,10 @@ Atomic loads produce :ref:`defined <memmodel>` results when they may see
1051510515
multiple atomic stores. The type of the pointee must be an integer, pointer, or
1051610516
floating-point type whose bit width is a power of two greater than or equal to
1051710517
eight and less than or equal to a target-specific size limit. ``align`` must be
10518-
explicitly specified on atomic loads, and the load has undefined behavior if the
10519-
alignment is not set to a value which is at least the size in bytes of the
10520-
pointee. ``!nontemporal`` does not have any defined semantics for atomic loads.
10518+
explicitly specified on atomic loads. Note: if the alignment is not greater or
10519+
equal to the size of the `<value>` type, the atomic operation is likely to
10520+
require a lock and have poor performance. ``!nontemporal`` does not have any
10521+
defined semantics for atomic loads.
1052110522

1052210523
The optional constant ``align`` argument specifies the alignment of the
1052310524
operation (that is, the alignment of the memory address). It is the
@@ -10655,9 +10656,10 @@ Atomic loads produce :ref:`defined <memmodel>` results when they may see
1065510656
multiple atomic stores. The type of the pointee must be an integer, pointer, or
1065610657
floating-point type whose bit width is a power of two greater than or equal to
1065710658
eight and less than or equal to a target-specific size limit. ``align`` must be
10658-
explicitly specified on atomic stores, and the store has undefined behavior if
10659-
the alignment is not set to a value which is at least the size in bytes of the
10660-
pointee. ``!nontemporal`` does not have any defined semantics for atomic stores.
10659+
explicitly specified on atomic stores. Note: if the alignment is not greater or
10660+
equal to the size of the `<value>` type, the atomic operation is likely to
10661+
require a lock and have poor performance. ``!nontemporal`` does not have any
10662+
defined semantics for atomic stores.
1066110663

1066210664
The optional constant ``align`` argument specifies the alignment of the
1066310665
operation (that is, the alignment of the memory address). It is the
@@ -10807,8 +10809,9 @@ must be at least ``monotonic``, the failure ordering cannot be either
1080710809
A ``cmpxchg`` instruction can also take an optional
1080810810
":ref:`syncscope <syncscope>`" argument.
1080910811

10810-
The alignment must be a power of two greater or equal to the size of the
10811-
`<value>` type.
10812+
Note: if the alignment is not greater or equal to the size of the `<value>`
10813+
type, the atomic operation is likely to require a lock and have poor
10814+
performance.
1081210815

1081310816
The alignment is only optional when parsing textual IR; for in-memory IR, it is
1081410817
always present. If unspecified, the alignment is assumed to be equal to the
@@ -10910,8 +10913,9 @@ the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not
1091010913
allowed to modify the number or order of execution of this
1091110914
``atomicrmw`` with other :ref:`volatile operations <volatile>`.
1091210915

10913-
The alignment must be a power of two greater or equal to the size of the
10914-
`<value>` type.
10916+
Note: if the alignment is not greater or equal to the size of the `<value>`
10917+
type, the atomic operation is likely to require a lock and have poor
10918+
performance.
1091510919

1091610920
The alignment is only optional when parsing textual IR; for in-memory IR, it is
1091710921
always present. If unspecified, the alignment is assumed to be equal to the

0 commit comments

Comments
 (0)