[llvm] [Docs][AMDGPU] availability/visibility in addrspace(3) (PR #212707)

Wed Jul 29 01:53:16 PDT 2026

https://github.com/ssahasra updated https://github.com/llvm/llvm-project/pull/212707

>From c6ea16dcf1e84166791afd116dfe37f6e2b3e371 Mon Sep 17 00:00:00 2001
From: Sameer Sahasrabuddhe <sameer.sahasrabuddhe at amd.com>
Date: Wed, 29 Jul 2026 13:47:36 +0530
Subject: [PATCH 1/3] [Docs][AMDGPU] availability/visibility in addrspace(3)

addrspace(3) on AMDGPU corresponds to LDS, which is a fast memory directly
accessed by all threads in a workgroup (there is no intervening cache). Thus,
any accesses to this addrspace have built-in availability and visibility at
"workgroup" scope.
---
 llvm/docs/AMDGPUMemoryModel.md | 67 +++++++++++++++++++++++++---------
 1 file changed, 50 insertions(+), 17 deletions(-)

diff --git a/llvm/docs/AMDGPUMemoryModel.md b/llvm/docs/AMDGPUMemoryModel.md
index c057909b0539c..226dfe2983963 100644
--- a/llvm/docs/AMDGPUMemoryModel.md
+++ b/llvm/docs/AMDGPUMemoryModel.md
@@ -126,47 +126,80 @@ these necessary conditions, and hence they can be explained using the rules from
 either memory model. But the new intrinsics and metadata *opt out* of the LLVM
 memory model, and can only be explained using the AMDGPU memory model.
 
+### Store-Available and Load-Visible
+
 (amdgpu-store-available)=
 
-### store-available
+#### store-available
 
 ```llvm
- at llvm.amdgcn.av.global.store.b128(ptr, value, scope)
-store atomic [syncscope("<target-scope>")]
-atomicrmw    [syncscope("<target-scope>")]
-cmpxchg      [syncscope("<target-scope>")]
+ at llvm.amdgcn.av.store.b128.p1(
+    ptr addrspace(1) %addr,
+    <4 x i32> %value,
+    metadata !scope)
 ```
 
 The `@llvm.amdgcn.av.global.store.b128` intrinsic performs a non-atomic
-*store-available* operation on `ptr` with scope `scope`.
+*store-available* operation on `%addr` with scope `!scope`.
+
+```llvm
+store atomic ..., [syncscope("<target-scope>")]
+atomicrmw    ..., [syncscope("<target-scope>")]
+cmpxchg      ..., [syncscope("<target-scope>")]
+```
 
 An atomic operation that results in a store operation is a *store-available*
 operation with scope `syncscope`.
 
+```llvm
+store ..., ptr addrspace(N) %addr
+```
+
+A `store` operation to `addrspace(3)` is always performed as a *store-available*
+operation with "workgroup" scope.
+
+A `store` operation to `addrspace(0)` is performed as a *store-available*
+operation with "workgroup" scope if the flat address resolves to `addrspace(3)`.
+
 (amdgpu-load-visible)=
 
-### load-visible
+#### load-visible
 
 ```llvm
- at llvm.amdgcn.av.global.load.b128(ptr, scope)
-load atomic  [syncscope("<target-scope>")]
-atomicrmw    [syncscope("<target-scope>")]
-cmpxchg      [syncscope("<target-scope>")]
+%value = @llvm.amdgcn.av.global.load.b128(
+             ptr addrspace(1) %addr,
+             metadata !scope)
 ```
 
 The `@llvm.amdgcn.av.global.load.b128` intrinsic performs a non-atomic
-*load-visible* operation on `ptr` with scope `scope`.
+*load-visible* operation on `%addr` with scope `!scope`.
+
+```llvm
+%value = load atomic ..., [syncscope("<target-scope>")]
+%value = atomicrmw   ..., [syncscope("<target-scope>")]
+%value = cmpxchg     ..., [syncscope("<target-scope>")]
+```
 
 An atomic operation that results in a read operation is a *load-visible*
 operation with scope `syncscope`.
 
+```llvm
+%value = load ..., ptr addrspace(N) %addr
+```
+
+A `load` operation to `addrspace(3)` is always performed as a *load-visible*
+operation with "workgroup" scope.
+
+A `load` operation to `addrspace(0)` is performed as a *load-visible* operation
+with "workgroup" if the flat address resolves to `addrspace(3)`.
+
 :::{note}
 Metadata cannot be used to model this using ordinary load/store operations,
 because the scope is necessary for correctness. In a hypothetical operation
 like this:
 
 ```llvm
-store ptr, data, !mmra !{!"amdgcn-av", !"workgroup"}
+store ptr addrspace(1) %ptr, <4 x i32> %value, !mmra !{!"amdgcn-av", !"workgroup"}
 ```
 
 If the metadata is dropped or ignored, there is no guarantee that the store
@@ -367,7 +400,7 @@ particular, the following instructions are equivalent.
 
 ```{list-table}
 :header-rows: 1
-:widths: 20 20 60
+:widths: 25 20 55
 
    * - LLVM
      - SPIRV
@@ -387,19 +420,19 @@ particular, the following instructions are equivalent.
    * - `load atomic`
      - `OpAtomicLoad`
      - `MakePointerVisible`. Also `MakeVisible` when order is at least `acquire`.
-   * - `load atomic !{!"amdgcn-av", !"none"}`
+   * - `load atomic`<br>`!{!"amdgcn-av", !"none"}`
      - `OpAtomicLoad`
      - `MakePointerVisible`
    * - `store atomic`
      - `OpAtomicStore`
      - `MakePointerAvailable`. Also `MakeAvailable` when order is at least `release`.
-   * - `store atomic !{!"amdgcn-av", !"none"}`
+   * - `store atomic`<br>`!{!"amdgcn-av", !"none"}`
      - `OpAtomicStore`
      - `MakePointerAvailable`
    * - `fence`
      - `OpMemoryBarrier`
      - `MakeAvailable` when order is at least `release`, and `MakeVisible` when order is at least `acquire`.
-   * - `fence !{!"amdgcn-av", !"none"}`
+   * - `fence`<br>`!{!"amdgcn-av", !"none"}`
      - `OpMemoryBarrier`
      - \-
 ```

>From 1a0baa2162e2054cc83b6ff4ce60823d7037770a Mon Sep 17 00:00:00 2001
From: Sameer Sahasrabuddhe <sameer.sahasrabuddhe at amd.com>
Date: Wed, 29 Jul 2026 13:56:42 +0530
Subject: [PATCH 2/3] fix copy-pasta

---
 llvm/docs/AMDGPUMemoryModel.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/AMDGPUMemoryModel.md b/llvm/docs/AMDGPUMemoryModel.md
index 226dfe2983963..e444081b4fd7b 100644
--- a/llvm/docs/AMDGPUMemoryModel.md
+++ b/llvm/docs/AMDGPUMemoryModel.md
@@ -133,7 +133,7 @@ memory model, and can only be explained using the AMDGPU memory model.
 #### store-available
 
 ```llvm
- at llvm.amdgcn.av.store.b128.p1(
+ at llvm.amdgcn.av.global.store.b128(
     ptr addrspace(1) %addr,
     <4 x i32> %value,
     metadata !scope)

>From c90f91af67782cc25d77acdcdaa60d196b6df085 Mon Sep 17 00:00:00 2001
From: Sameer Sahasrabuddhe <sameer.sahasrabuddhe at amd.com>
Date: Wed, 29 Jul 2026 14:21:59 +0530
Subject: [PATCH 3/3] add addrspace names, also update intrinsics to match
 AMDGPU Usage Manual

---
 llvm/docs/AMDGPUMemoryModel.md | 37 +++++++++++++++++-----------------
 llvm/docs/AMDGPUUsage.rst      |  2 ++
 2 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/llvm/docs/AMDGPUMemoryModel.md b/llvm/docs/AMDGPUMemoryModel.md
index e444081b4fd7b..fba3aadb32958 100644
--- a/llvm/docs/AMDGPUMemoryModel.md
+++ b/llvm/docs/AMDGPUMemoryModel.md
@@ -133,14 +133,12 @@ memory model, and can only be explained using the AMDGPU memory model.
 #### store-available
 
 ```llvm
- at llvm.amdgcn.av.global.store.b128(
-    ptr addrspace(1) %addr,
-    <4 x i32> %value,
-    metadata !scope)
+ at llvm.amdgcn.av.store.b128(%addr, %value, metadata !scope)
 ```
 
-The `@llvm.amdgcn.av.global.store.b128` intrinsic performs a non-atomic
-*store-available* operation on `%addr` with scope `!scope`.
+The `@llvm.amdgcn.av.store.b128` intrinsic performs a non-atomic
+*store-available* operation on `%addr` with scope `!scope`. See
+{ref}`amdgpu-av-load-store` for details.
 
 ```llvm
 store atomic ..., [syncscope("<target-scope>")]
@@ -155,24 +153,24 @@ operation with scope `syncscope`.
 store ..., ptr addrspace(N) %addr
 ```
 
-A `store` operation to `addrspace(3)` is always performed as a *store-available*
-operation with "workgroup" scope.
+A `store` operation to `addrspace(3)` (local or LDS) is always performed as a
+*store-available* operation with "workgroup" scope.
 
-A `store` operation to `addrspace(0)` is performed as a *store-available*
-operation with "workgroup" scope if the flat address resolves to `addrspace(3)`.
+A `store` operation to `addrspace(0)` (generic or flat) is performed as a
+*store-available* operation with "workgroup" scope if the flat address resolves
+to `addrspace(3)`.
 
 (amdgpu-load-visible)=
 
 #### load-visible
 
 ```llvm
-%value = @llvm.amdgcn.av.global.load.b128(
-             ptr addrspace(1) %addr,
-             metadata !scope)
+%value = @llvm.amdgcn.av.load.b128(%addr, metadata !scope)
 ```
 
-The `@llvm.amdgcn.av.global.load.b128` intrinsic performs a non-atomic
-*load-visible* operation on `%addr` with scope `!scope`.
+The `@llvm.amdgcn.av.load.b128` intrinsic performs a non-atomic *load-visible*
+operation on `%addr` with scope `!scope`. See {ref}`amdgpu-av-load-store` for
+details.
 
 ```llvm
 %value = load atomic ..., [syncscope("<target-scope>")]
@@ -187,11 +185,12 @@ operation with scope `syncscope`.
 %value = load ..., ptr addrspace(N) %addr
 ```
 
-A `load` operation to `addrspace(3)` is always performed as a *load-visible*
-operation with "workgroup" scope.
+A `load` operation to `addrspace(3)` (local or LDS) is always performed as a
+*load-visible* operation with "workgroup" scope.
 
-A `load` operation to `addrspace(0)` is performed as a *load-visible* operation
-with "workgroup" if the flat address resolves to `addrspace(3)`.
+A `load` operation to `addrspace(0)` (generic or flat) is performed as a
+*load-visible* operation with "workgroup" if the flat address resolves to
+`addrspace(3)`.
 
 :::{note}
 Metadata cannot be used to model this using ordinary load/store operations,
diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index 2a4f290effc6d..9b829dcf9e818 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -2114,6 +2114,8 @@ The AMDGPU backend implements the following LLVM IR intrinsics.
 
    List AMDGPU intrinsics.
 
+.. _amdgpu-av-load-store:
+
 '``llvm.amdgcn.av``' Intrinsics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

