[llvm-branch-commits] [llvm] [LangRef][AMDGPU] Specify that syncscope can cause atomic operations to race (PR #189015)

[Fabian Ritter via llvm-branch-commits]

https://github.com/ritter-x2a created https://github.com/llvm/llvm-project/pull/189015

Targets should be able to specify that the syncscope of atomic operations
influences whether they participate in data races with each other.

For example, in AMDGPU, we want (and already implement) the load in the
following case to be in a data race (i.e., return `undef` according to the
current definition), because there is an atomic store with workgroup syncscope
executing in a different workgroup:

```
; workgroup 0:
  store atomic i32 1, ptr %p syncscope("workgroup") monotonic, align 4

; workgroup 1:
  store atomic i32 2, ptr %p syncscope("workgroup") monotonic, align 4
  load atomic i32, ptr %p syncscope("workgroup") monotonic, align 4
```

This is consistent with the behavior of, e.g., [heterogeneous-race-free (HRF)
memory models](https://research.cs.wisc.edu/multifacet/papers/asplos14_hrf.pdf)
and the [HSA memory model](https://hsafoundation.com/standards/).

>From 715d22eac720a9c9355b2f16c73aa12a20609490 Mon Sep 17 00:00:00 2001
From: Fabian Ritter <fabian.ritter at amd.com>
Date: Fri, 27 Mar 2026 10:35:54 -0400
Subject: [PATCH] [LangRef][AMDGPU] Specify that syncscope can cause atomic
 operations to race

Targets should be able to specify that the syncscope of atomic operations
influences whether they participate in data races with each other.

For example, in AMDGPU, we want (and already implement) the load in the
following case to be in a data race (i.e., return `undef` according to the
current definition), because there is an atomic store with workgroup syncscope
executing in a different workgroup:

```
; workgroup 0:
  store atomic i32 1, ptr %p syncscope("workgroup") monotonic, align 4

; workgroup 1:
  store atomic i32 2, ptr %p syncscope("workgroup") monotonic, align 4
  load atomic i32, ptr %p syncscope("workgroup") monotonic, align 4
```

This is consistent with the behavior of, e.g., [heterogeneous-race-free (HRF)
memory models](https://research.cs.wisc.edu/multifacet/papers/asplos14_hrf.pdf)
and the [HSA memory model](https://hsafoundation.com/standards/).
---
 llvm/docs/AMDGPUUsage.rst | 5 ++++-
 llvm/docs/LangRef.rst     | 3 ++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index 1ede5ca2d4cf6..8ea0fa17518de 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -1144,7 +1144,10 @@ The memory model supported is based on the HSA memory model [HSA]_ which is
 based in turn on HRF-indirect with scope inclusion [HRF]_. The happens-before
 relation is transitive over the synchronizes-with relation independent of scope
 and synchronizes-with allows the memory scope instances to be inclusive (see
-table :ref:`amdgpu-amdhsa-llvm-sync-scopes-table`).
+table :ref:`amdgpu-amdhsa-llvm-sync-scopes-table`). Concurrent atomic operations
+only operate atomically with respect to each other if they are included in each
+other's sync scope. If a read R and the writes it may see are atomic but do not
+all have inclusive scopes, then R returns ``undef`` (see :ref:`memmodel`).
 
 This is different to the OpenCL [OpenCL]_ memory model which does not have scope
 inclusion and requires the memory scopes to exactly match. However, this
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 9e734caa3b497..bbe8ac4a44275 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3933,7 +3933,8 @@ Given that definition, R\ :sub:`byte` is defined as follows:
 -  Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may
    see are atomic, it chooses one of the values written. See the :ref:`Atomic
    Memory Ordering Constraints <ordering>` section for additional
-   constraints on how the choice is made.
+   constraints on how the choice is made. Targets may impose additional
+   requirements on R and the writes it may see based on their ``syncscope``.
 -  Otherwise R\ :sub:`byte` returns ``undef``.
 
 R returns the value composed of the series of bytes it read. This