atomic.9: provide fine details about CAS memory model MD semantic

Reviewed by:	markj
Discussed with:	alc
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differential revision:	https://reviews.freebsd.org/D52744

1 files changed, 27 insertions, 0 deletions

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.