[llvm] [docs] Reflect C++'s read-write and write-read coherence rules in the LLVM memory model (PR #217849)

[Fabian Ritter via llvm-commits]

================
@@ -4170,10 +4170,24 @@ happens-before must be perfectly overlapping to act atomically.
     read-modify-write operation M ({ref}`cmpxchg <i_cmpxchg>` and
     {ref}`atomicrmw <i_atomicrmw>`) reads from a perfectly overlapping
     `monotonic` (or stronger) write W, W must be immediately before M in
-    the relevant modification order. If one atomic read happens before
-    another perfectly overlapping atomic read and both are at least
-    `monotonic`, the later read must not see an earlier value in the
-    address's modification order. This disallows reordering of perfectly
+    the relevant modification order.
+
+    Atomic accesses that are `monotonic` (or stronger) satisfy coherence rules:
+    - read-read coherence: If an atomic read R1 happens before another
+        perfectly overlapping atomic read R2, R1 reads from a
+        perfectly overlapping atomic write W, and R1, R2, and W are all
+        at least `monotonic`, then R2 must not read from writes that are
+        earlier than W in the address's modification order.
+    - read-write coherence: If an atomic read R happens before a
+        perfectly overlapping atomic write W and both are at least
+        `monotonic`, R must not read from writes that are later than W
----------------
ritter-x2a wrote:

Technically, that's not necessary: the may-see rules in the [main memory model section](https://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations) say that, if R happens-before W, R may not see W. But it still makes sense to avoid confusing readers, so I've added "...R must not read from **W or** writes that are later than W...".

> Maybe "R must read from a write earlier than W in the address's modification order"?

I think that's a construct we need to avoid here. It works in C and C++ (without atomic_ref) because there, monotonic reads really can only read from monotonic writes (which are in the address's modification order) due to strict aliasing, but in the LLVM setting a monotonic read should also be able to read from unordered or non-atomic writes (which are not in the address's modification order).

https://github.com/llvm/llvm-project/pull/217849