[llvm-branch-commits] [llvm] [AMDGPUUsage] Specify what one-as syncscopes do (PR #189016)
Fabian Ritter via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Fri Mar 27 07:48:04 PDT 2026
https://github.com/ritter-x2a created https://github.com/llvm/llvm-project/pull/189016
This matches the currently implemented and (as far as I could determine)
intended semantics of these syncscopes.
The sync scope table is unchanged except for removing its indentation;
otherwise it would be rendered as part of the preceding note.
>From 19e1d98982feaac5aad73fb29f77e00b9e47d563 Mon Sep 17 00:00:00 2001
From: Fabian Ritter <fabian.ritter at amd.com>
Date: Fri, 27 Mar 2026 10:42:22 -0400
Subject: [PATCH] [AMDGPUUsage] Specify what one-as syncscopes do
This matches the currently implemented and (as far as I could determine)
intended semantics of these syncscopes.
The sync scope table is unchanged except for removing its indentation;
otherwise it would be rendered as part of the preceding note.
---
llvm/docs/AMDGPUUsage.rst | 204 ++++++++++++++++++++------------------
1 file changed, 108 insertions(+), 96 deletions(-)
diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index 8ea0fa17518de..7e31cf7345e4a 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -1153,102 +1153,114 @@ 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
is conservatively correct for OpenCL.
- .. table:: AMDHSA LLVM Sync Scopes
- :name: amdgpu-amdhsa-llvm-sync-scopes-table
-
- ======================= ===================================================
- LLVM Sync Scope Description
- ======================= ===================================================
- *none* The default: ``system``.
-
- Synchronizes with, and participates in modification
- and seq_cst total orderings with, other operations
- (except image operations) for all address spaces
- (except private, or generic that accesses private)
- provided the other operation's sync scope is:
-
- - ``system``.
- - ``agent`` and executed by a thread on the same
- agent.
- - ``workgroup`` and executed by a thread in the
- same work-group.
- - ``wavefront`` and executed by a thread in the
- same wavefront.
-
- ``agent`` Synchronizes with, and participates in modification
- and seq_cst total orderings with, other operations
- (except image operations) for all address spaces
- (except private, or generic that accesses private)
- provided the other operation's sync scope is:
-
- - ``system`` or ``agent`` and executed by a thread
- on the same agent.
- - ``workgroup`` and executed by a thread in the
- same work-group.
- - ``wavefront`` and executed by a thread in the
- same wavefront.
-
- ``cluster`` Synchronizes with, and participates in modification
- and seq_cst total orderings with, other operations
- (except image operations) for all address spaces
- (except private, or generic that accesses private)
- provided the other operation's sync scope is:
-
- - ``system``, ``agent`` or ``cluster`` and
- executed by a thread on the same cluster.
- - ``workgroup`` and executed by a thread in the
- same work-group.
- - ``wavefront`` and executed by a thread in the
- same wavefront.
-
- On targets that do not support workgroup cluster
- launch mode, this behaves like ``agent`` scope instead.
-
- ``workgroup`` Synchronizes with, and participates in modification
- and seq_cst total orderings with, other operations
- (except image operations) for all address spaces
- (except private, or generic that accesses private)
- provided the other operation's sync scope is:
-
- - ``system``, ``agent`` or ``workgroup`` and
- executed by a thread in the same work-group.
- - ``wavefront`` and executed by a thread in the
- same wavefront.
-
- ``wavefront`` Synchronizes with, and participates in modification
- and seq_cst total orderings with, other operations
- (except image operations) for all address spaces
- (except private, or generic that accesses private)
- provided the other operation's sync scope is:
-
- - ``system``, ``agent``, ``workgroup`` or
- ``wavefront`` and executed by a thread in the
- same wavefront.
-
- ``singlethread`` Only synchronizes with and participates in
- modification and seq_cst total orderings with,
- other operations (except image operations) running
- in the same thread for all address spaces (for
- example, in signal handlers).
-
- ``one-as`` Same as ``system`` but only synchronizes with other
- operations within the same address space.
-
- ``agent-one-as`` Same as ``agent`` but only synchronizes with other
- operations within the same address space.
-
- ``cluster-one-as`` Same as ``cluster`` but only synchronizes with other
- operations within the same address space.
-
- ``workgroup-one-as`` Same as ``workgroup`` but only synchronizes with
- other operations within the same address space.
-
- ``wavefront-one-as`` Same as ``wavefront`` but only synchronizes with
- other operations within the same address space.
-
- ``singlethread-one-as`` Same as ``singlethread`` but only synchronizes with
- other operations within the same address space.
- ======================= ===================================================
+There is a ``one-as`` variant for each sync scope. If a ``release`` or
+``acquire`` operation with a ``one-as`` sync scope participates in a
+synchronization, only the effects of memory operations in the address space of
+the ``one-as`` operation are synchronized. The address space of a ``fence``
+instruction with ``one-as`` sync scope is specified via
+``amdgpu-synchronize-as`` MMRAs (see :ref:`amdgpu-fence-as`).
+
+.. note::
+ The behavior of ``one-as`` sync scopes is currently not well-founded in the
+ memory model. Synchronization via a ``one-as`` sync scope effectively causes
+ the happens-before relation to be non-transitive.
+
+.. table:: AMDHSA LLVM Sync Scopes
+ :name: amdgpu-amdhsa-llvm-sync-scopes-table
+
+ ======================= ===================================================
+ LLVM Sync Scope Description
+ ======================= ===================================================
+ *none* The default: ``system``.
+
+ Synchronizes with, and participates in modification
+ and seq_cst total orderings with, other operations
+ (except image operations) for all address spaces
+ (except private, or generic that accesses private)
+ provided the other operation's sync scope is:
+
+ - ``system``.
+ - ``agent`` and executed by a thread on the same
+ agent.
+ - ``workgroup`` and executed by a thread in the
+ same work-group.
+ - ``wavefront`` and executed by a thread in the
+ same wavefront.
+
+ ``agent`` Synchronizes with, and participates in modification
+ and seq_cst total orderings with, other operations
+ (except image operations) for all address spaces
+ (except private, or generic that accesses private)
+ provided the other operation's sync scope is:
+
+ - ``system`` or ``agent`` and executed by a thread
+ on the same agent.
+ - ``workgroup`` and executed by a thread in the
+ same work-group.
+ - ``wavefront`` and executed by a thread in the
+ same wavefront.
+
+ ``cluster`` Synchronizes with, and participates in modification
+ and seq_cst total orderings with, other operations
+ (except image operations) for all address spaces
+ (except private, or generic that accesses private)
+ provided the other operation's sync scope is:
+
+ - ``system``, ``agent`` or ``cluster`` and
+ executed by a thread on the same cluster.
+ - ``workgroup`` and executed by a thread in the
+ same work-group.
+ - ``wavefront`` and executed by a thread in the
+ same wavefront.
+
+ On targets that do not support workgroup cluster
+ launch mode, this behaves like ``agent`` scope instead.
+
+ ``workgroup`` Synchronizes with, and participates in modification
+ and seq_cst total orderings with, other operations
+ (except image operations) for all address spaces
+ (except private, or generic that accesses private)
+ provided the other operation's sync scope is:
+
+ - ``system``, ``agent`` or ``workgroup`` and
+ executed by a thread in the same work-group.
+ - ``wavefront`` and executed by a thread in the
+ same wavefront.
+
+ ``wavefront`` Synchronizes with, and participates in modification
+ and seq_cst total orderings with, other operations
+ (except image operations) for all address spaces
+ (except private, or generic that accesses private)
+ provided the other operation's sync scope is:
+
+ - ``system``, ``agent``, ``workgroup`` or
+ ``wavefront`` and executed by a thread in the
+ same wavefront.
+
+ ``singlethread`` Only synchronizes with and participates in
+ modification and seq_cst total orderings with,
+ other operations (except image operations) running
+ in the same thread for all address spaces (for
+ example, in signal handlers).
+
+ ``one-as`` Same as ``system`` but only synchronizes with other
+ operations within the same address space.
+
+ ``agent-one-as`` Same as ``agent`` but only synchronizes with other
+ operations within the same address space.
+
+ ``cluster-one-as`` Same as ``cluster`` but only synchronizes with other
+ operations within the same address space.
+
+ ``workgroup-one-as`` Same as ``workgroup`` but only synchronizes with
+ other operations within the same address space.
+
+ ``wavefront-one-as`` Same as ``wavefront`` but only synchronizes with
+ other operations within the same address space.
+
+ ``singlethread-one-as`` Same as ``singlethread`` but only synchronizes with
+ other operations within the same address space.
+ ======================= ===================================================
Target Types
------------
More information about the llvm-branch-commits
mailing list