git: 074fc34c842c - stable/15 - atomic.9: provide fine details about CAS memory model MD semantic

The branch stable/15 has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=074fc34c842c00d31f6c4edc13cea66110652062

commit 074fc34c842c00d31f6c4edc13cea66110652062
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2025-09-26 06:58:36 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2025-11-09 00:35:53 +0000

    atomic.9: provide fine details about CAS memory model MD semantic
    
    (cherry picked from commit 269b1c238806c7fb8835a0510b224c466ca3efa0)
---
 share/man/man9/atomic.9 | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/share/man/man9/atomic.9 b/share/man/man9/atomic.9
index 674959648330..b027a0ff0bca 100644
--- a/share/man/man9/atomic.9
+++ b/share/man/man9/atomic.9
@@ -242,6 +242,33 @@ section.
 However, they will not prevent the compiler or processor from moving loads
 or stores into the critical section, which does not violate the semantics of
 a mutex.
+.Ss Architecture-dependent caveats for compare-and-swap
+The
+.Fn atomic_[f]cmpset_<type>
+operations, specifically those without explicitly specified memory
+ordering, are defined as relaxed.
+Consequently, a thread's accesses to memory locations different from
+that of the atomic operation can be reordered in relation to the
+atomic operation.
+.Pp
+However, the implementation on the
+.Sy amd64
+and
+.Sy i386
+architectures provide sequentially consistent semantics.
+In particular, the reordering mentioned above cannot occur.
+.Pp
+On the
+.Sy arm64/aarch64
+architecture, the operation may include either acquire
+semantics on the constituent load or release semantics
+on the constituent store.
+This means that accesses to other locations in program order
+before the atomic, might be observed as executed after the load
+that is the part of the atomic operation (but not after the store
+from the operation due to release).
+Similarly, accesses after the atomic might be observed as executed
+before the store.
 .Ss Thread Fence Operations
 Alternatively, a programmer can use atomic thread fence operations to
 constrain the reordering of accesses.